API design

Improve your API experience

Paint developer portals with an aesthetic brush. Improve developer experience with usability, hypermedia, pagination, RESTful design, and more.

Advice on API Design


What’s New in OpenAPI 3.0

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

The End of API Documentation As We Know It

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

New eBook Released: API Design on the Scale of Decades

Introducing a new title from the Nordic APIs writing team! For this eBook, we took 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

4 Design Tweaks to Improve API Operations

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

Is GraphQL The End of REST Style APIs?

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, more 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

How Could Artificial Intelligence Improve API Design?

Until relatively recently, artificial intelligence was firmly planted in the realm of science fiction. However, with the advent of more 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

The Benefits of a Serverless API Backend

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

Standard API Definitions Demystified

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

Use Automatic API Documentation Testing To Supercharge API Growth

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

Designing a True REST State Machine

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

9 Common Errors Made During API Testing

9 Common Errors Made During API Testing

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

Ultimate Guide to 30+ API Documentation Solutions

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

3 Methods to Documenting JSON APIs

3 Methods for Documenting JSON API Services

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 widely used, the open…

Read More

The Easiest Way to Generate API Documentation

The Easiest Ways to Generate API Documentation

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

Read More

How to Wrap a REST API in GraphQL

How to Wrap a REST API in GraphQL

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

Asynchronous APIs in Choreographed Microservices

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, more 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

5 Potential Benefits of Integrating GraphQL

GraphQL is incredibly powerful — so powerful, in fact, that it is used by corporations such as Facebook 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

Building and Enforcing an Internal API Style Guide

API Design: Building and Enforcing an Internal Style Guide

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

Your API is never fully released

Your API is Never Fully Released

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

Top Specification Formats for REST APIs

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 more than any other tool within the API provider’s grasp. In this piece,…

Read More

How Far Should API Definition Languages Go?

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

Read More

The Evolution of the OpenAPI Specification: Does OpenAPI Mean Open World?

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

Why API Developer Experience Matters More Than Ever

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.

Beautiful UI Design for API Developer Portals

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


API Design & Testing State of the Art

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

Content Negotiation For Web API Longevity

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

How to Improve API Experience Using Hypermedia

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

Sweet API — Syntactic Sugar and You

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 shared, 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

Sessions on API Design


HTML Hypermedia APIs and Adaptive Web Design
Gustaf Nilsson Kotte - Jayway - March 2013

The many different types of connected devices are increasing dramatically. We already have a large amount of duplicate code between client applications (both native and web), and the increasing number of devices is only making this worse. Also, cheap low-end devices are gaining greater market shares, and users expect a good experience when using our software on them. To solve the problem of code duplication on the clients, we need to pull as much of it as we can back from the clients to the server. A good way to achieve this is to build a Hypermedia API and to use HTML as the media type for the API. 

Microservices Anti-Patterns
Tammer Saleh - Pivotal Software - 21/20/2014

It seems everyone’s talking about microservices, lately, but few appear to have given any real thought to best practices around building and deploying them. In this talk, we’ll highlight many of the mistakes we’ve seen people make when building a microservices architecture

Token-Based Architecture Design
R. Kevin Nelson - 21/10/2014

In the course of designing and using web APIs, you’re bound to encounter tokens. They are everywhere: access tokens for OAuth, CSRF tokens for security, reset tokens for passwords. Because of their ubiquity, they’re easy to overlook, but token design actually plays a huge role in shaping your application architecture. This presentation surveys API architectural archetypes through the lens of tokens, and how they can facilitate (or inhibit) your platform’s scalability.

Developers are People Too! Building a DX based API Strategy
Ronnie Mitra - Layer 7 Technologies - September 2013

When it comes to user experience in consuming APIs, Ronnie Mitra is the one to talk to. Listen to his session to understand what it takes to implement consistent usability standards throughout your API's onboarding process and ongoing usage.

More sessions on API Design

Ebooks on API Design

API Design on the Scale of Decades

Expert Insights from the 2016 Nordic APIs Platform Summit, dedicated to the theme of architecting and designing APIs on the scale of decades.

Winter 2015 Blog Post Collection

We consolidated our 11 favorite blog posts from the winter season into an easy to view eBook, spreading insights founded on hundreds of business representatives that we met with during our 2014 seminars. API architects are realizing that APIs need to be conceived with their target consumer in mind, whether human or machine. This effected…

Read More