13
Growing APIs

This chapter covers

• API lifecycle
• API design guidelines
• API reviews
• Communication and community

Throughout this book, we have expanded our vision of API design and APIs in general beyond simple application programming interfaces floating in the air. This is especially true of the four previous chapters. In chapters 10 and 11, you saw how to pay attention to not only the consumer’s but also the provider’s context to design realistic APIs that will be implementable and will fulfill consumers' needs in the most efficient way. And by thinking beyond an API’s current version, you learned in chapter 9 to create API designs that reduce the risk of introducing breaking changes when modifying them.

Designing APIs requires us to think beyond the APIs themselves because they are just one part of the whole. We started to uncover this whole in chapter 12. Indeed, you discovered that API designers can do more than just create APIs by participating in the making of different types of documentation. In this last chapter, we will explore three other API-design-related topics that any API designer must be aware of, and sometimes master, in order to grow their APIs in the long run.

We will talk first about the API lifecycle: how APIs are born, live, and are eventually retired. Then we will explore API guidelines, which are mandatory when designing multiple APIs or multiple versions of a single API, whether working alone or with other designers. After that, we will take a look at the different ways of reviewing APIs in order to ensure that a design conforms to the organization’s API surface, fulfills expectations, is implementable, and pleases consumers. We will finish by talking about communication and sharing your APIs, their evolutions, and your API practices.

13.1 The API lifecycle

Growing APIs requires that we know the API lifecycle and understand that it runs in parallel with others, as shown in figure 13.1. As you can see, API design is only a part of the API lifecycle: how APIs are born, live, and eventually retire.

Figure 13.1 The API lifecycle

The API lifecycle starts with the analyze phase, where a company/organization/team/individual thinks providing an API might be of interest for business or technical reasons. During this phase, topics are explored, such as the API’s goals, what needs it is supposed to fulfill, what consumers it targets, who needs it, and what benefits it offers. Then comes the design phase, in which the ideas resulting from the Analyze phase are deeply investigated and transcribed into a programming interface contract. After that, during the implement phase, an application exposing this contract is built.

The analyze, design, implement journey is actually an iterative process; you might have to go back and forth according to new discoveries, new questions, or simply because you change your mind on a given design solution. After all this, the API is made available to the targeted consumers in the publish phase. The API will run this way until it evolves to provide new features. But it can also be retired because a new version introducing breaking changes is needed, with the previous version being replaced by the new one. Unfortunately, APIs can also be retired because they were unsuccessful or are simply not needed anymore.

An entire book, if not several, would be necessary to explore the full API lifecycle in depth. In the rest of this chapter, we will focus on topics relevant to API design and designers, but these topics are not confined to the design phase. More often than not, API designers must intervene in various stages of the API lifecycle and do more than just design APIs.

To guarantee success, designers must work closely with stakeholders, product owners, technical writers, and developers or testers. They also have to work closely with consumers, either directly or through the API’s developer relations team. And when working on an API, API designers participate in the creation of different types of documentation (as you saw in the previous chapter), take part in various reviews on both the provider’s and the consumer’s side, and can also have a hand in communications about the API.

But organizations rarely build a single, never-changing API; instead, they typically produce multiple, always-evolving APIs. The API designers have to work together to build a consistent API surface for the organization (see section 6.1). API designers must share what they do, helping each other by providing guidance when designing and reviewing APIs. Even lone API designers have to guide themselves by keeping an eye on their past work in order to be consistent in their design.

13.2 Building API design guidelines

Put two API designers in a meeting room and ask them how to handle pagination in a REST API. You’ll probably witness a lively discussion with each one proposing different methods and assessing the pros and cons of the other’s suggested solutions. And in the end, you might be presented with several options, all valid, and some different from the one(s) used in your existing organization or team’s APIs, which were created by either the same designers or other ones.

You saw in section 6.1 that consistency is a key concern when designing APIs. APIs have to be consistent with themselves, with the rest of the organization/team’s APIs, and also with the rest of the world in order to be easy to use. Being consistent over time when working alone on a single API is easier said than done, but when many API designers are working on an organization’s API surface, which is composed of many APIs, it’s hard to keep this surface totally smooth. We are humans; we all have our own preferences and backgrounds, and sometimes we change our minds without even noticing.

When new designers arrive, they have to discover how your APIs need to be designed in order to be consistent. But without proper guidance, they might not succeed. Similarly, if people who have never designed APIs before want to do so, it would be wise to provide them with adequate guidance to avoid API design catastrophes.

Defining guidelines, a set of rules that will be used by all designers, is a must to ensure consistency within and across the organization/team’s APIs. It’s also a good way to avoid wasting time with endless debates where everyone is right, but a single solution has to be chosen, and to focus on what really matters: providing the easiest to understand and easiest to use representations of APIs that fulfill consumers' needs. What’s more, guidelines are a wonderful tool to help beginning API designers. Let’s see what the contents of such guidelines might look like and how to actually create them.

13.2.1 What to put in API design guidelines

API design guidelines can be composed of three different layers: reference guidelines that focus on describing the foundations of the API designs, use case guidelines that explain how to apply these foundations through various uses cases, and design process guidelines that provide guidance about how to design APIs. Such guidelines can also provide information that goes beyond the interface contract, such as details about software architecture and implementation principles. Let’s take a closer look at each possible layer of the design guidelines, what it contains, and why you should think about including it in your API’s guidelines.

Reference guidelines

Being consistent in API design requires the definition of principles and rules that should be applied when designing APIs. Reference guidelines are the minimum API design guidelines that you must create: these list and describe all of the principles and rules. Figure 13.2 shows an excerpt of the Banking Company’s reference guidelines.

Figure 13.2 The Banking Company’s API design principles

The most basic reference guidelines might, for example, describe which HTTP methods, status codes, or headers can be used and when; the format of the resources' paths; what data formats are returned in the case of errors; and how to handle pagination. Such guidelines should also provide clear and shared definitions of the vocabulary used when designing APIs; for example, what is an API, what is a resource or a collection, what is a path, and what is a version? If you have heard of domain-driven design, this could be compared to the ubiquitous language that has to be used by all people involved in the design of APIs.

The reference guidelines can be compared to the API reference documentation: it lists and describes all the elements that you need when designing APIs. Like reference documentation, these can be quite indigestible alone, and it might not be that easy to design APIs that actually respect them. That is why you should also consider adding use case guidelines.

Use case guidelines

You should know by now that usability and the user’s point of view matter when you design anything. You have witnessed that when learning to design APIs, as well as their documentation. Obviously, API design guidelines are no exception: you must create those with usability and simplicity in mind. If you don’t do this, it’s better not to write them at all because at best, some people might read them but not fully follow them; and at worst, nobody will want to read them at all! The use case guidelines provide ready-to-use “recipes” or solutions as shown in figure 13.3.

Figure 13.3 A use case description in the Banking Company’s API design guidelines

The Create an Element page describes a use case using ordinary vocabulary, providing variants of a typical create, and then explains how to do that in a REST API using a shared vocabulary. It describes which parameters are expected, their format, and what kind of feedback should be provided, mentioning only the needed rules or principles coming from the reference guidelines.

Such documentation is really important for beginners, but it is also useful to seasoned API designers too. Some API designers might only do this work from time to time, and they might not be comfortable with technical API designers' vocabulary. Some of them might stick to the CRUD actions and find it hard to design a goal that is not something like create xyz; they’re usually tempted to use POST /do-this. They might also not know which HTTP status to choose if the reference guidelines only provide an inventory of authorized HTTP status codes without many details about when exactly to use them. If they haven’t read all the principles, they might have missed that a Location header was supposed to be returned when creating a resource (even seasoned API designers can forget this!).

Both beginners and seasoned designers will be more efficient and happier if they can find all the information they need in a single page without having to scan through all the principles and rules. But how did the designers know that they had to add a create something goal to the API?

Design process guidelines

Designing APIs requires methods, tools, and processes. It can be useful to add design process guidelines to your API guidelines, as shown in figure 13.4.

Figure 13.4 The Banking Company’s How to Design APIs page in the design guidelines

The idea is not to copy and paste text from this book or some other software design book into your guidelines. Such guidelines can simply provide a design canvas or links to existing documents or checklists, or to training sessions provided by seasoned API designers. You learned in chapters 10 and 11 that designing an API is not simply a matter of designing an interface contract floating in mid-air. There are many considerations around the creation of APIs that could be included in your guidelines.

More than interface design guidelines

Extended API design guidelines could contain information about security, network concerns, or implementation, as shown in figure 13.5. These might include details on the standard data attached to security tokens, which OAuth flow to use in a given context, or how to configure frameworks in order to actually get the expected results when implementing the API.

Figure 13.5 The Banking Company’s Implementation considerations page in the design guidelines

Basically, you can put anything you think is relevant in your API design guidelines to ensure consistency and to help people who design and build the APIs. But so far, we’ve only talked about what to put in the guidelines, not how to actually build them. We’ll turn to that next.

13.2.2 Continuously building guidelines

Building API design guidelines requires us not only to actually write them, but also to evolve them and make people aware of them and accept them.

Start small and accurate

When writing API design guidelines, don’t try to construct the best possible guidelines covering every possibility and every edge case in one shot. You will waste your time and end up producing rambling, low-quality documentation. Instead, start by covering basic, necessary topics in a simple and straightforward way. Aim for completeness and accuracy. This is not the time to start inventing fancy ways of using HTTP!

As mentioned in section 6.1.4, you can also be inspired by others, especially your favorite APIs. If there are APIs that you really love to use, why not copy their style? Similarly, you can take advantage of existing API guidelines that other companies share publicly, instead of inventing your own.

If your API design guidelines start small, that means they will evolve. Indeed, they must be allowed to evolve to include new contents related to situations that were not covered in the beginning.

Evolve, adapt, and fix

Rather than progressively adding everything that comes into your head in your API design guidelines, the idea is to only add field-proven content that has been used to solve an actual design question. Guidelines might also have to be fixed if some rules, use cases, or other content is revealed to be a burden to apply or inconvenient in the long run. And you might realize that you need different types of guidelines depending on the context. You could, for example, choose to use gRPC APIs internally and REST ones over the internet.

Evolving API design guidelines obviously means dealing with breaking changes, versioning, and change logs. The guidelines basically describe APIs, so remember what you learned in section 9.1 when modifying existing rules. You need to be aware of possible breaking changes and version your guidelines accordingly. Don’t forget to list the changes made in each version to avoid having designers keep trying to do things the way they were described in the previous version.

Build collectively, no dogma

Just because you write guidelines does not mean that all the API designers in your team/organization/company will magically be aware of them or accept them. What will happen if you write guidelines and just put them on a shelf or in a wiki? Absolutely nothing. You will have to communicate; you will have to promote those. You have to tell the designers that guidelines exist, and that they are there to help people avoid wasting time reinventing the wheel and to help them solve design problems. You will have to explain why consistency matters. You might have to explain why a specific rule has been chosen (by the way, it’s a good idea to write down in your rules why they exist!).

But simply saying all this might not be sufficient to make people accept your guidelines. After all, we all have our own backgrounds and points of view. You might be tempted to bluntly enforce the use of your guidelines and cross over to the dark side of governance. Please don’t.

Building API design guidelines is not something that should be done alone by a single designer, or worse, by someone who has never put an API into production. The guidelines should be built collectively by actual designers for actual designers, without dogma, always willing to adjust/add/fix/evolve and even derogate when necessary. API design guidelines must not be enforced at all costs by the API police, and they should not reflect the ideas and preferences of a single individual. A whole book would be needed to thoroughly explain how exactly to proceed, but I think you get the idea.

13.3 Reviewing APIs

What could go possibly wrong when creating APIs? Everything. Even if you’ve read this book. Well, it might be less risky if you’ve read it, but things can still go wrong if the APIs are not reviewed. Let’s illustrate this with another story.

One day, at the Banking Company, someone decided they needed to be able to send emails to customers. So they designed an API to do so. The idea was to later add other functions, like sending SMSs or notifications. That sounded like a good plan at first.

The API design was submitted to the company’s API designers’ guild for some advice. But before even analyzing the proposed design, someone in the guild asked why this send email goal was used and in what context. The answer was that when customers modified their personal data via the mobile application or website, such as changing their mailing or email address, they needed to receive an email confirming that the modification had been made and informing them that if they had not requested the change, they should immediately contact the Banking Company. The goal was supposed to be called by the website or mobile app after the update customer goal was called. This was considered a problem because it could mean that it was up to consumers to know that an email must be sent when updating the customer’s information. Analyzing the design revealed other significant problems.

The send email goal was represented as a POST /send-email request awaiting an email address and a message. Such a request does not respect the company’s API guidelines: consumers would need to know the customer’s email address and what message should be sent to use it. But all that was nothing compared to the security hole that this API would have caused. The API would have exposed on the internet a way to send emails with any content to anyone on behalf of the Banking Company!

APIs have to be reviewed (validated, analyzed, scrutinized, checked, tested, and so on) at various stages of the API lifecycle to ensure that they work as intended. First and foremost, the needs have to be clearly identified and well understood, and it must be verified that creating an API is actually the best solution.

Once the API is designed, its interface contract must be linted in order to check that it’s free of errors and, in the case of modifications, free of breaking changes. Then it must be validated from the provider’s perspective: does it fulfill the identified needs, and is it secure, implementable, and evolvable? It must also be validated from the consumer’s perspective: is it understandable and usable in the consumers' contexts? And last but not least, once the API is implemented, the implementation has to be tested in order to ensure that it actually exposes the expected interface contract.

API designers typically participate actively or at least have a say in all these reviews. Designers should obviously participate in reviews of the APIs they are working on, but they can also give a hand with reviews of other APIs. Getting feedback from others is always rewarding and helps ensure quality. Also, getting feedback from experienced API designers helps beginners to improve. Conversely, helping with the design of other people’s APIs is rewarding because it’s a good way to broaden one’s perspective and discover new design use cases and ideas.

As an API designer, it is your job to question, challenge, investigate, validate, and analyze everything regarding the design of your APIs. But you must also keep an eye on the overall context—everything around the design—to ensure that the directions taken are the right ones. (Remember chapter 11 where you learned how to design an API in context?)

The idea is to absolutely not act as a hostile expert who knows everything and impose your will on everyone else, but rather to participate in growing the APIs beyond their design in the best possible manner, as everyone in the team/organization should be seeking to do.

13.3.1 Challenging and analyzing needs

In the send email use case, asking why and in what context this goal was to be used revealed that the imagined need was not the actual need and that the proposed solution was not secured at all. The real need was not to send an email but to notify customers of activity in their profiles. And in the end, the implemented solution was not a REST web API but a publish/subscribe system (see section 11.3.2).

Indeed, it was eventually decided to create a new Customer Notification server application relying on events sent by the Customer application. With this solution, the Customer application, which exposes the API with the update customer goal, sends a customer updated event when a customer’s data is modified. The Customer Notification application subscribes to these events. It holds all knowledge about how to notify customers, like their preferred channel (email, mobile app notification, or SMS), and the related data, such as their email address and phone number. It only reacts to selected events: in this first version, an update of the customer’s data.

Such a decoupled architecture separates concerns, is flexible, and can easily evolve, while at the same time being secure and fulfilling the actual need. The implemented solution is completely different from what was imagined at first. It’s a good thing the Banking Company’s API guild conducted a review before starting to code! The send email API was designed for nothing, and this waste of time could have been avoided if the review had been carried out earlier.

You learned in chapter 2 that an API must fulfill consumers' needs to avoid creating terrible Kitchen Radar APIs, or worse, insecure send email goals as we have just seen. These perceived consumer needs have to be carefully evaluated and challenged in order to spot the real needs and find adequate, implementable, and secure solutions.

So before thinking about which URLs or HTTP methods to use, before even thinking about filling in an API goals canvas, you have to challenge and analyze the identified needs. And this should be done as early as possible. Once needs have been vaguely identified, they must be discussed and evaluated prior to anything else. Figure 13.6 shows an example of a checklist that can be used to challenge and analyze the needs you identify; it is based on this book’s contents, but feel free to adapt it to your own situation.

Figure 13.6 Challenging needs checklist

Analyzing needs is not reserved to APIs. Clearly identifying the needs or problems to solve must be done when building anything. There is no single best approach for challenging and analyzing needs; you can use your favorite method.

Asking questions, such as why something needs to be done, what the context is, and how it will be used, usually helps to identify the real need or needs hidden by the first demand. The 5 Whys method is also a good way of doing this: you simply ask “why?” and get a response, then ask “why?” again about the response to go deeper into the analysis. Doing this five times in a row is usually sufficient to find the real root need. All these elements impact the design of the solution and the API.

After that, you must also investigate the consumer’s and provider’s contexts (see chapters 10 and 11) and think about security (see section 8.1.4). All of this is an iterative process that should be undertaken with various participants (those who are involved in defining the needs, implementation, security, and so on).

Clearly identifying the needs and investigating the context will ensure that the most appropriate solution is designed, whether it involves adding new goals to an existing API, creating a new API, or building something that is not an API or where an API is only part of the solution. If an API is the solution, having clearly identified needs will ensure that the goals the API helps to achieve are actually the right ones.

13.3.2 Linting the design

Was the proposed POST /send-email request awaiting an optional email as a string and msg as a number a valid one? It uses a resource path that doesn’t look like what you learned to use in section 3.2.3, but maybe the Banking Company’s API design guidelines say that APIs have to be function-based (see section 11.3). Still, for clarity, shouldn’t msg be called message and shouldn’t it be a string? And is it normal to have all the expected properties be optional? Linting the proposed design will give answers to all these questions:

“Lint, or a linter, is a tool that analyzes source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. The term originates from a Unix utility that examined C language source code.”

Wikipedia

Just like code, an API design can contain errors (for example, using the wrong type for a property) and might have to be written (designed) following conventions like using the errorMessage property name instead of err_msg. Linting the API will help detect these kinds of errors and others.

API linting consists of checking for bugs in the design, as well as verifying that it conforms to the design guidelines and is consistent with any preexisting elements (we explore what those are in a moment). While linting an API design, you should also check its security and documentation. That is, you basically lint anything that you would put in an API description file; indeed, you have to check every aspect of the interface contract. Figure 13.7 shows an example of a linting checklist.

Figure 13.7 An example API linting checklist

Basically, you have to analyze each model and its properties and each goal and its parameters and responses. You also have to analyze the goal flows and security definitions. Most of these checks are quite simple and binary, but there are three types of verification that you should take particular care with: checking the documentation, checking flows, and (most importantly) checking consistency with preexisting elements.

Checking the documentation of the interface contract is important because having an exhaustively documented interface contract will facilitate design reviews from both the provider’s and the consumer’s perspective. We talk about this in the following sections (13.3.3 and 13.3.4).

Checking flows is basically what you learned to do in section 2.3 and section 3.3.4. It’s quite simple, but critical, to ensure that the API actually works. It would be embarrassing, if not disastrous, if consumers could not use the API because they were unable to provide some parameters.

Checking consistency with preexisting elements is perhaps the most difficult check, but it’s a very important one. Verifying that a name, data model, or goal’s behavior is consistent with preexisting elements requires concentration and detailed knowledge of what actually exists inside and beyond the API that is being linted. Otherwise, you can end up with, for example, three different address formats, two different standard ways of representing countries, too many ways of showing that an amount is invalid, and a totally custom way of representing phone numbers.

Preexisting elements mostly come from the API itself, other APIs from the organization, and standards; they can be names, types, data models, and even behaviors. To verify that an API is consistent with preexisting elements in the API itself or other APIs from the same organization, you can rely partly on your API designer’s sense. Also, if you’ve had the good fortune to participate in reviews of other APIs, you might have a few memories of what you have seen. But it’s hard to keep up with everything that can be happening across the organization’s API surface, so you should also rely on available API documentation. It can be helpful to enable a search mechanism across all of your APIs' documentation to facilitate such an analysis.

Regarding identifying standards that could be used instead of custom formats, this is up to you, your API designer’s sense, and your favorite search engine. There are obvious standards you will have heard of, like ISO 8601 for dates and ISO 4217 for currencies, but you can’t possibly be aware of all the existing standards. For example, did you know there’s a standard for representing phone numbers? It’s the E.164 format, defined by the International Telecommunication Union (ITU).

You should always check if a standard exists to represent a given data item. If you find one, add it to your guidelines immediately. It might be a burden at the beginning; but in the long run, it will make your life easier as you will quickly catalog all the standards you need for your APIs. And in case of evolution of an existing API, do not forget to check if you are introducing some breaking changes. If they cannot be avoided, you will have to apply your versioning policy.

Linting can be partially automated by running some tools on a machine-readable API description format, but a human will still need to be involved. It’s fairly simple to check path formats or if an HTTP status code is authorized, but it’s quite complex to check that a human-readable description is relevant. While it’s not possible to fully automate the process, taking advantage of automation for linting is highly recommended so reviewers can focus on the checks that actually need human beings.

Finally, be aware that linting an API design only validates the form, not the substance. It only ensures that the designed interface contract respects certain design rules. It absolutely does not validate that the API fulfills all of the provider’s requirements and that consumers will actually want and be able to use it. Once linted, an API must therefore be reviewed in depth from both the provider’s and consumer’s perspectives.

13.3.3 Reviewing the design from the provider’s perspective

Just because you have identified the real needs and contextual elements required to design an API, and its design has been fully linted, doesn’t mean everything is OK from the provider’s perspective. Indeed, you have to check with the whole team that the resulting API design actually fulfills all of the provider’s requirements. You’ll want to confirm that the design satisfies all the identified needs and that it is secure, implementable, and extensible. Figure 13.8 shows another example of a checklist inspired by this book’s content that you can use for this purpose. Again, feel free to adapt it to your needs.

Figure 13.8 Checking the design from the provider’s perspective

If you have used the API goals canvas, created exhaustive documentation, and applied what you have learned in this book to design the interface contract, such a review should not be a problem at all. The API goals canvas will help to link initial needs and API goals. The documentation is important here to facilitate the review for all the people involved who don’t have your extensive knowledge of the API.

The various goal flows must match the identified needs, and each goal must behave as expected, returning the correct data and triggering the correct errors. Each element should be reasonably extensible (remember section 9.3). Also, don’t forget to check that each goal, behavior, or returned response can actually be handled by the implementation and that the performance of each goal and flow matches expectations. But this review only concerns the provider’s perspective; we must not forgot to also check that everything is OK from the consumer’s perspective.

13.3.4 Reviewing the design from the consumer’s perspective

Last but not least in the design analysis is the review from the consumer’s perspective. Is the API easy to use, easy to understand, and efficient? Does it take care not to unduly expose the provider’s perspective? If not, all the effort you’ve put into creating the API will be worth nothing because nobody will want to use the resulting product (see section 1.2.3). Hopefully, all that you have learned in this book should make this review a piece of cake. Figure 13.9 shows an example checklist for reviewing an API’s design from the consumer’s perspective, based on this book’s content. As usual, feel free to adapt it to your needs.

Figure 13.9 Checking the design from the consumer’s perspective

During this review, you have to take the place of a consumer who does not know anything about the API. Check that each goal and its parameters and responses (especially the errors) make sense for consumers and are not a vile exposition of what’s happening under the hood (the despised provider’s perspective). Verify that each required parameter is really required in order to request minimal data. Pay particular attention to the names and descriptions: check that they are not provider’s jargon. Check also that the goal flows are simple and efficient, without too many steps and with goals that prevent errors. And don’t forget to check that the performance estimates (for single goals and goal flows) are valid for both basic and complex use cases (see section 10.1).

Finally, once all the verifications have been done—API linting (see section 13.3.2), provider review, and consumer review—the API can at last be implemented. But your job does not necessarily stop here. You might have to help verify that the implementation actually implements the designed interface contract as expected.

13.3.5 Verifying the implementation

I will not explain how to actually test the implementation of an API because that’s outside the scope of this book. There are many tools out there for doing so, and some of them even allow you to generate tests based on API description files. But these tests are usually insufficient to verify that the implementation does everything that is expected, so tests will have to be written.

The implementers might rely on various levels of testing (usually unit tests and API tests) to entirely validate an API. What I want to do here is show you a few things that should particularly be taken care of and warn you about a few traps.

Never bypass security testing

Security testing for APIs is mandatory. You must ensure that access controls and sensitive data are actually handled in the proper way.

For access control, the first level of testing consists of ensuring that only registered consumers can access the API and that they cannot do anything outside of the granted scopes. The second level of testing concerns consumer/end user permission controls. For example, if a consumer requests a list of accounts on behalf of an end user, only that user’s accounts must be returned. And if the same consumer requests account 12345, the API must only return it if the end user is actually authorized to get it.

Regarding sensitive data, you have to ensure that undue sensitive data is not returned. If sensitive data has to be requested or returned, you must ensure that it is properly secured (using a nonsensitive representation or encryption, for example) as discussed in section 8.4.

Be careful when using generated documentation to validate the implementation

Some implementation frameworks allow you to generate an API description file from the code at runtime or while building the application. This generated file could be compared to the original API description file to validate that the interface contract exposed by the implementation conforms to the expected one. But such validation can only be done on elements that do not come from annotations specifically made to generate the API description file.

If, for example, I add in my code an API description-specific annotation to indicate that the possible values for a type attribute are checking and savings, there is no guarantee that my code will actually only return these values. This information is only declarative.

Some tools can leverage standard annotations that are prescriptive, however. For example, if I develop a web application exposing an API with the Java Spring Boot framework, I can use a standard annotation to declare that a method maps to the POST /transfers request. Such values can be used in a comparison between an original API description file and a generated one.

Check the interface contract at runtime

Even if you find a magic trick, framework, or tool that allows you to generate the actually implemented interface contract, you must test the implementation at runtime to validate all expected behaviors. Just because the generated and valid interface contract states that a 400 Bad Request response is returned in the case of a missing mandatory attribute doesn’t mean it’s actually the case.

Check properties' characteristics in responses

When the interface contract says that a property is required or mandatory in a returned data model, it must always be returned. The same is true if the API description provides information about minimum and maximum values, number of items in arrays, and so on. Do not forget these tests.

Check the whole network chain

When testing your API, you must make test calls encompassing the whole network chain in front of the implementation. This network chain can include firewalls, proxies, and VIP or API gateways, for example. Firewalls are good purveyors of bugs; misconfigured ones can, for example, block DELETE HTTP requests or replace HTTP 5XX status codes with 500 responses or return an HTML page (no kidding) instead of data in case of error.

Also, misconfigured API gateways can implement some controls on behalf of the implementation based on the API description file used to expose the API, but not necessarily in the best way. For example, these can return one error at a time or use the wrong error format (using the gateway standard error format which happens to be different from the API’s one, or worse, an HTML page—again, no kidding).

13.4 Communicating and sharing

The end is near; this is the last section of the last chapter of the book. I want to take this opportunity to talk briefly about communicating and sharing as an API designer. As you might have noticed while reading this last chapter, API designers do not work alone. An API designer has to work, at the least, with the people who want to create the APIs or think that an API could be the solution, the consumers, the people in charge of developing the implementation, the people in charge of security, those in charge of documentation, and other API designers.

As an API designer, you have to be able to share what you do, your design material. To make it easy to do so, you should at least use a standard API description format. You might also want to take advantage of a source control system like Git to store your files, use wikis for less-structured descriptions, build a custom API catalog, or use an off-the-shelf developer portal.

To ensure consistency, your company’s guidelines (that you contribute to) should be easily accessible and known to all the API designers. All the existing APIs and data models should at least be easily findable (hence the source control system, wiki, or API catalog) and, if possible, searchable.

To design with confidence, never hesitate to have your designs reviewed by peers. It could also be useful and informative to create or participate in an API designer community (or API guild). And most importantly, make sure your designs are reviewed by actual consumers.

Summary

• Documentation is vital to designing, building, and validating APIs.
• Consistency is impossible without API design guidelines and documentation.
• Designing APIs must not be done alone: work with others on reviews and/or build a designers community.
• API designers participate in the whole API lifecycle.
• In order to design effective and useful APIs, API designers must challenge and deeply analyze the needs their APIs are intended to fulfill.