Advice on API Design
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…
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….
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…
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…
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…
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,…
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…
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…
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…
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,…
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…
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…
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…
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.
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