BLOG POSTS on API Design
Featured

Back in 2006, Google discovered that an extra 500 milliseconds of latency could drop traffic by as much as 20%. That was twelve years ago; now web users expect faster responses than ever before, and as an API practitioner, it’s your duty to make that happen! Building ultra fast APIs isn’t easy, especially not when…
Read More

We all know that using a well-designed API is extremely rewarding, while using a poorly-designed API can be frustrating enough for us to give up altogether. However, when we ourselves strive to build the best-designed APIs possible, we tend to trip up right away, wondering: what makes an API’s design good or bad? For Arnaud Lauret,…
Read More

Release management is an important part of any API development lifecycle. That being said, it is also consistently overloed, often considered as an afterthought than a foundational element of the API and business environment. This is unfortunate, as implementing proper release management can not only prevent significant issues from arising, it can also improve…
Read More

API design is a complex topic — what works for some providers does not for others. It seems that with each year, new approaches are developed, and new thoughts on how APIs fit into the overall platform strategy emerge. We’re specifically seeing this occur in banking, as market trends force agile ways of bringing…
Read More

With all of the and proclamations about REST, we can sometimes forget that it’s simply one of many options. REST is a very good standard for a wide variety of APIs, but there are other API design styles for nuanced scenarios. To help API developers make sense of which API design style to…
Read More

What kind of API style should you be using? From SOAP, to REST, GraphQL, and new styles like gRPC, there are many competing standards for designing APIs and the way consumers interact with them. We’ve written about each before, but as the industry changes rapidly, there are always new concerns and opportunities for comparison. In…
Read More

HATEOAS is, in essence, a value proposition and definition for what an API should do. HATEOAS, or Hypermedia as the Engine of Application State, is a specific constraint upon the REST architecture. For many, however, HATEOAS seems a nit-picky addition to the slew of API design best practices. Part of this comes from the fact…
Read More

While it’s extremely important to have quality API developer experience, it does not stop at great API design or at the documentation level. One of the most important elements of great developer experience is the SDK. For app developers, an SDK is often the point of entry to elements within the API. Every forked API,…
Read More

SQL is old — about 40 years old, in fact. In the tech world, where a new framework or language pops up seemingly every day, 40 years feels downright archaic. Why is such an old language relevant to building APIs in 2018? Because SQL is so old, it has a long history from which to…
Read More

There’s a good reason why building APIs can be extremely tough and time-consuming: they have to cater to both human and machine needs. Inherently, this is pretty difficult. Machines are picky and rely on pure logic; they crave rigid, hierarchical structures and definite instructions. On the other hand, humans prefer things to work on an…
Read More

Today, new application development leans towards microservices and serverless approaches. With this paradigm shift, the weaknesses of traditional RESTful API approaches began to show. GraphQL was developed in response to the problems of a typical REST API, but requires a fair amount of configuration to get it running server-side. According to Nikolas Burk, full-stack developer,…
Read More

One of the greatest struggles an API provider can face is how to manage versions and builds from instance to instance. The constant need to iterate matched with the constant need to organize has made versioning a controversial and often discussed facet of modern API development. There are some alternatives to traditional versioning, however, that…
Read More

This post is included in our eBo on GraphQL. Download a free copy here! We’ve talked about GraphQL at length previously, and for very good reason – GraphQL is, in many ways, one of the powerful tools an API provider has in terms of providing singular endpoints to the consumer and controlling data flow….
Read More

In the world of API craft, no area is hotly discussed than design. From REST, gRPC, to GraphQL, there are many approaches to designing and standardizing web API interactions. Today we turn our focus to another approach, JSON API, a specification for building APIs detailed at JSONAPI.org. JSON API, described at JSONAPI.org, is great…
Read More

Change is inevitable and growth is a good thing. When your API has reached the point of expanding beyond it’s original intent and capacity, it’s time to consider the next version. Whether that next iteration is a whole number version bump or just a feature expansion, it’s important to consider the pros and cons of…
Read More

Developer experience is a vital component of API design. The best developer experience will result in a better, stronger, useful API, and by extension, a better, stronger, useful end user experience. While developer experience is very much a subjective thing that is highly dependent on the developer consumer, there are nonetheless some recurring…
Read More

This week Nordic APIs hosted the Platform Summit, our largest conference to date. 400+ attendees and 60+ speakers arrived to a sold out event, jam-packed with the industry’s leading experts on web APIs. Our attendees represented 26 different countries, making this our most most global event ever. With tremendous growth slated for the API economy, we encouraged our…
Read More

An API provider is akin to a handyman. To fix a specific problem, a specific solution is needed, and a skilled handyman is the only one with the experience, the know-how, and the ability to fix these issues. The same is true in the API space. To continue the allegory, just like a handyman…
Read More

If there’s anything that has the most “bang for the buck” in the IT world, it’s optimization. Optimization, or the process of simplifying, offloading, or otherwise reducing the processing demand of an entity, can have significant benefits to almost any system, and when done properly, can take even the most monolithic system into the realm…
Read More

Big news in the world of APIs! Today, the Open API Initiative (OAI) released its 3.0.0 version of the OpenAPI Specification. In case you missed our past coverage of this evolving specification, the OpenAPI Spec (OAS) has quickly become an industry standard method to describe web APIs. The OpenAPI Specification was transmuted from Swagger, and…
Read More

There are very few names as ubiquitous as Google. While Google is best known for its search engine and for its suite of productivity applications, some of its most powerful work is in the functional aspects of the world wide web and the protocols that drive it. To this end, Google’s gRPC is a powerful…
Read More

We’ve discussed GraphQL at length previously – and while the discussions on how GraphQL works are obviously very powerful, we’ve yet to dive into some of the best practices that should be adopted when developing a GraphQL-centric API. Today, we’re going to do exactly that. We’re going to discuss the best practices for healthy GraphQL…
Read More

APIs are, by design, vastly interconnected. In order to effectively function and carry out the purposes for their creation, APIs are crafted to connect easily to other services, both internal and external. While this certainly is beneficial from a user perspective, developers often find the result of this type of development to have some problematic…
Read More

If you’ve been hiding under a rock for the past 18 months you may not know that the Swagger API specification, arguably the most popular specification format available to the API community, has been donated to the Linux Foundation to become the bedrock of the OpenAPI Specification. The OpenAPI Specification (OAS) is supported by various…
Read More

On the one hand, having proper API documentation can be a sign of early success for an API provider, allowing new users to effectively understand the functionalities and caveats behind an API solution. On the other hand, extensive documentation could indicate an overly complex solution with far too many variables to navigate. Even in those…
Read More

Introducing a new title from the Nordic APIs writing team! For this eBo, we to the top 15 most popular YouTube sessions from our last Platform Summit, and wrote companion chapters that dove into each topic. Download this volume and get the latest API Design advice the industry has to offer! Grab a FREE copy…
Read More

We’ve previously discussed best practices when it comes to designing an API with quality developer experience. But what will the long term operational repercussions be for the design moves we make now? For example, if URLs are designed without metadata to describe actions, later on, product owners will have a difficult time staring at unintelligible…
Read More

The world of APIs is one of innovation and constant iteration. The technologies that once drove the largest and best solutions across the web have been supplanted by new, innovative solutions. That is why it’s surprising, then, that many developers have clung to what they consider the bastions of web API development. Such a…
Read More

Until relatively recently, artificial intelligence was firmly planted in the realm of science fiction. However, with the advent of powerful processors and groundbreaking research into deep learning, AI has inched ever closer to reality. The question now is, since we have this tech, how can we use it to improve existing systems? Are there…
Read More

Imagine if your backend had no infrastructure. No permanent server, nowhere for your API to call home. Sounds a bit bleak, doesn’t it? As it turns out, serverless backends could be the next big thing for implementing truly scalable cloud architecture. How do you make an Application Programming Interface lightweight on the client side, yet…
Read More

As with any industry, the web API space faces different approaches to standardization. Not least of which are the differences between how API providers choose to define their APIs in a machine readable way with API specifications and description languages. API definitions have emerged as ways to annotate API functionalities, and there are still many…
Read More

It’s a universal truth that testing for errors, and debugging any that show up, isn’t a fun process. Almost all API providers are familiar with the process of monitoring and testing. Before you commit code, API behaviors must be thoroughly vetted, as with any software release. So why is it that when it comes to…
Read More

There are many misconceptions surrounding what exactly Representational State Transfer (REST) is. The prime of which is the concept of hypermedia, or defined in full context, Hypermedia as the engine of application state (HATEOAS). Jargon aside, hypermedia is actually a valuable idea that many self-touted “RESTful” web APIs do not adhere to. Hypermedia places heightened operational…
Read More

API testing is an important facet of the API development process. Such testing can help disclose important security flaws, data processing errors, and even breaks in basic functionality. With all that said, it’s an unfortunate fact that many API testing processes are fundamentally flawed, and because of this, issues are often kept around and extended…
Read More

Say you have developed a web API and now want to show it to the world. Next comes documentation, and guess what — there’s a tool for that. But, in a sea of API documentation generation tools, which one is suitable to your specific environment? This comprehensive list of API documentation solutions has been curated specifically for web…
Read More

JSON is a very powerful, open standard format that is used by many services and APIs across the internet. Unfortunately, while open standard carries a lot of good, it also creates some pitfalls that developers may not be prepared to handle. One of these pitfalls is that, in combination with being wiy used, the open…
Read More

Whether you’re a startup developing your first API or an established player in the API economy, the truth is becoming steadily apparent; providing quality API documentation is vital to the success of an API initiative. API documentation is an important part of the product offering, ivering affordances to the developer community to help them…
Read More

GraphQL is a powerful tool that we’ve discussed previously at Nordic APIs. As with any emergent tool in the API space, however, there’s some disagreement on exactly how to implement it, and what the best practices for its implementation and use case scenarios are. Have no fear, dear reader — we’re here to sort this…
Read More

Over 300 API practitioners. 53 talks. 6 demos. 3 workshops. 3 days. Endless coffee. Sound familiar? If you’re into APIs and were in Stockholm this week you were probably experiencing the 2016 Platform Summit — the Nordic region’s largest web API event to date. For this three day event we brought some of the most dignified…
Read More

When building microservices you have to first make a decision: How am I going to manage service-to-service communication? Most developers will answer immediately: API calls. But then, questions come to mind: Am I going to call services directly? Doesn’t it block the caller service? Doesn’t it introduce a dependency between both services? What if…
Read More

GraphQL is incredibly powerful — so powerful, in fact, that it is used by corporations such as to drive their large, complex social systems for billions of users. Despite this, the language is still relatively nascent, and its usage has yet to reach the dizzying heights that those languages it replaces and augments occupy….
Read More

RESTful design is akin to the graphical user interface on modern computers — ubiquitous enough to be considered the de facto choice, but in practice, not necessarily the only option. REST is certainly considered by many to be the king of the hill, but it’s wrong to think it’s the only player in town. In…
Read More

In our recent post on tips for starting a public API journey we touched briefly on the idea of creating a style guide that helps API providers produce well-constructed and consistent APIs as part of their public API offering. The creation of an API style guide is, however relevant for API providers regardless of whether…
Read More

The modern development landscape has changed from when APIs were first being developed. Gone are the days where developers could “develop and forget”, releasing APIs, systems, or applications to the public for consumption and use. Today, there isn’t really such a thing as a release in the common parlance of yesteryear. When a developer releases…
Read More

Now that the Nordic APIs World Tour is finished, let’s circle back to sum up what we learned. During our tour, expert API practitioners d their insights with attendees at 4 cities, touching on API development, security, design, operations, and during intimate conference settings. A recurring theme in many talks was API Design. So,…
Read More

Documentation will set you free. Whether your API is for internal, private use, or for extensive public interaction, proper documentation can make or break an API. It’s not just a tool for developers, either — proper API documentation can drive API adoption than any other tool within the API provider’s grasp. In this piece,…
Read More

The most common API definition languages we spot in the wild are Swagger / OpenAPI Spec, RAML and API Blue. All three let you define your endpoints, your resources, your query or path parameters, your headers, status codes, security schemes, and . In a nutshell, these definition languages define the structure of your API, and…
Read More

Following the fanfare of its introduction in late 2015, the OpenAPI Initiative has now been in existence for six months. As discussed on their blog a great deal of progress has been made towards creating the governance structure that will help the OpenAPI Specification (OAS) move forwards, including a home on GitHub that has been…
Read More

Whether or not you focus on DX design, your developers are always experiencing your API, and that experience may either be positive or negative. Ronnie Mitra is the director of API design at the API Academy, which has a singular focus on API design and implementation best practices. Mitra is an advocate that an API must be designed with its reader in mind.

When we think of Application Programming Interfaces — APIs — we may not immediately pair them with User Interface design. Implemented as a background tool, APIs are largely in the hands of developers, and technical documentation has a natural reputation of being elusive for laymen. However, this mindset is not sustainable. User Interface (UI) is…
Read More

Ensuring proper APIs functionality raises all the following questions: How do you decide which endpoints you’re going to expose with your API? How do you create all the documentation that developers will use to interact with your API? What is the best way to verify that your API is working as specified by the documentation,…
Read More

Every so often, a new image file format comes along that does a better job of compressing images than JPEG or PNG. We’ve seen Google pushing its own Webp format, (purportedly 26% smaller in size compared to PNGs), and new formats BPG and FLIF are contenders, packaging images in less and less space and time…
Read More

One of the greatest ways to improve and sustain an API userbase is by enhancing developer experience. A way to do this is by improving the usability of an API with hypermedia — a method of interacting with APIs. But what exactly is hypermedia, why is it important, and how will it affect an API…
Read More

The internet is bar none the most effective and amazing tool for connecting people. What it’s historically not, however, is an effective and amazing tool for connecting people with systems. While networks form and information is d, the underlying systems have historically been hidden underneath complex code and abstraction. Enter syntactic sugar, a syntax that…
Read More
More posts on API Design