Evolving APIs

Many APIs simply do not change that much, especially if they’re designed by people who understand the domain extremely well. For example, most of the external tax calculators have static APIs. Have a quick look at Avalara’s tax API as an example. The underlying tax rates and sometimes the formulas change, but the actual API you call is fairly static. The response you get back is also fairly static. The US could adopt a VAT-style tax system and the APIs still wouldn’t change. Most APIs you interact with on a day-to-day basis are like this.

Inevitably, APIs need to evolve—but not necessarily change. Let’s say you’re building a customer profile API that allows simple create, read, update, and delete (CRUD) operations. The following code shows the object that the API would need for a new customer to be created.

{
  "id": "c12345",
  "firstName": "Kelly",
  "lastName": "Goetsch",
  "email": "[email protected]"
}

Now let’s say that your business users want to capture your customers’ shoe sizes so they can be targeted with better product offers. Your JSON object would now look like this:

{
  "id": "c12345",
  "firstName": "Kelly",
  "lastName": "Goetsch",
  "email": "[email protected]",
  "shoeSize": 12
}

This is an evolution of your API, which should be easily supported without versioning. If the client doesn’t specify the shoeSize parameter, the application shouldn’t break. This goes back to Postel’s law, which states that you should be “liberal in what you accept and conservative in what you send.” When applied to APIs, Postel’s law essentially means you shouldn’t do strict serializations/deserializations. Instead, your code should be tolerant of additional attributes. If shoeSize suddenly appears as an attribute, it shouldn’t break your code. Your code should just ignore it. For example, the serializer we use allows for the following annotation:

// To ignore any unknown properties in JSON input wuthout exception:
@JsonIgnoreProperties(ignoreUnknown=true)

If you adopt a strict approach to serialization, any difference in the client and server is going to break the client:

Unhandled exception
org.springframework.oxm.jaxb.JaxbUnmarshallingFailureException:
  JAXB unmarshalling exception: unexpected element
  (uri:"http://yyy.org", local:"xxxResponse").
  Expected elements are <{}xxx>,<{}xxxResponse>;

The approach of having evolving APIs goes back to Bertrand Meyer’s open/closed principle, which he documented in his 1988 book, Object-Oriented Software Construction. In it, he said that software entities (especially APIs) should be “open for extension but closed for modification.” He went on to further say:

A module will be said to be open if it is still available for extension. For example, it should be possible to add fields to the data structures it contains, or new elements to the set of functions it performs.

A module will be said to be closed if it is available for use by other modules. This assumes that the module has been given a well-defined, stable description (the interface in the sense of information hiding).

The majority of APIs you have will fall into this category. Simply add attributes where you can, and don’t break existing functionality.

The major advantage of this approach is that the APIs remain fairly static, allowing clients to code to them more easily. It’s one less dimension for developers to care about. The supplier of the API only has one version of the codebase to support in production at any given time, dramatically simplifying bug fixing, logging, monitoring, etc.

The disadvantage of this approach is that the APIs are fairly locked from the start. Vendors who solely adopt this approach lose the flexibility to radically change the APIs, which is perfectly acceptable in many cases.

For APIs that change more radically and where true A/B testing is necessary, versioning is the preferred approach.

Versioning APIs

With versioning, the provider of the APIs deploys more than one major version of an API to the same environment at the same time. For example, versions 1, 2, and 3 of the pricing API may be live in production all at the same time. All versions can serve traffic concurrently.

While there are many flavors of versioning, a common approach is to guarantee API compatibility at the major version level but continually push minor updates. For example, clients could code to version 1 of an API. The vendor responsible for the implementation of the API can then publish and deploy versions 1.1, 1.2, 1.3, and beyond over time to fix bugs and implement new features that don’t break the published API. Later, that team can publish version 2, which breaks API compatibility with version 1.

Clients (e.g., point of sale, web, mobile, and kiosk) can request a specific major version of an API when making an HTTP request. By default, they should get the latest minor release of a major version. This is often done through a URL (e.g., /Inventory/v2/ or /Inventory?version=v2) or through HTTP request headers (Accept: application/vnd.example.api+json;version=2).

This is great for vendors who are rapidly innovating. It allows them to release minimum viable products. When enough is learned, they can fork the codebase and then offer the old version 1 and have an entirely new breaking API as version 2. The vendor isn’t “locked in” to a specific API, as is the issue with evolving APIs.

The major challenge you’ll have with versioning is persistent data. Here, there are essentially two approaches: you can have one datastore per major API version (Figure 3-4), or you can have one datastore per environment (Figure 3-5).

Figure 3-4. One data store per version

Figure 3-5. One data store per environment

If you have one datastore per major API version, then you need to migrate or continually synchronize the data between major versions. If your client was using version 1 of the order API, and then you start using version 2, you need to physically move or synchronize the data from version 1 to version 2. You can’t just seamlessly switch over to version 2, for example. This is hard to do when you have multiple clients because it requires that you cut all your (potentially dozens of) clients over to the new version of the API at the same time. Facebook has gone so far as to offer an upgrade utility to help developers transition from one version to another.

If you have one datastore per environment, with all API versions hitting the same datastore, you have the problem of “evolving” the objects. Your point-of-sale system could write an order object using version 1 of the API and, five seconds later, your iOS application could try to amend that order using version 2 of the same API. Any API version can write an object, and any API version can update that order at any time. This is by far the most common approach, but it’s hard to do.

Versioning is only used because it offers more freedom to innovate, especially in a fast-changing environment. Evolving APIs are easier to support, but both the clients and the producer of the APIs tend to get locked in over time, slowing the pace of change.

Local Testing

Testing APIs locally is pretty easy. Just download Postman, Advanced REST Client, Insomnia REST Client, or any of the myriad of GUI-based tools that allow you to execute HTTP requests against a REST resource, and see the response (Figure 3-6). You can even use traditional cURL if you’re inclined to use the command line. The purpose of this testing is to verify that uncommitted changes you’ve made locally don’t break the API.

Figure 3-6. Postman HTTP client

Traditionally, local testing was hard because you’d have to run an entire multigigabyte application locally, including the UI, application server and database. There was no way to test out the backend functionality without exercising the frontend. But it’s actually pretty easy to test your APIs if you’re just building APIs. The frontend developers can test their stack independently.

Unit Testing

While local testing is focused on individual developers testing uncommitted changes, unit testing is focused on ensuring that the API you’re working on as a team (often a microservice team) works as expected. The API is the unit you’re testing. An API is really just a contract, if you look at the big picture. When unit testing, you’re verifying that the API is working as advertised. 

Unit testing must be 100% automated and baked into your Continuous Integration/Continuous Delivery (CI/CD) pipeline. It should exercise all aspects of the API, including its functionality and especially the HTTP response codes it produces. If you version your APIs, your tests should cover supported versions of your APIs as well.

For example, let’s pretend you have a /Product/{id} HTTP REST resource. When you call it with /Product/12345, you get back the following response:

{
   "product":
   {
      "id" : "12345",
      "name" : "Test product",
      "description" : "Long description..."
   }
}

To test this functionality, you can use any number of frameworks. Let’s use a simple example using REST Assured. It would look something like this:

@Test public void
product_resource_returns_200_with_expected_product_name() {
    when().
            get("/Product/{id}", "12345").
    then().
            statusCode(200).
            body("product.name", equalTo("Test product"));
}

You can very easily hook this into any CI/CD pipeline so that each of your APIs is rigorously tested with each code commit.

Load Testing

In addition to testing the functionality of each API, you should also test its scalability limits. Again, you don’t know who’s consuming your API or what they’re doing with it. 

Any load testing framework out there can make an HTTP request to test an API. Common frameworks include ApacheBench, Gatling, and JMeter. If your API is backed by a microservice-style application and deployed to a public cloud with auto-scaling, you should have no problems scaling your APIs.

Integration Testing

Once you’ve verified that an individual API works and performs well under load, it then must be tested within the context of other APIs in the ecosystem.

Figure 3-7 shows a fairly common end-to-end flow you’d want to test.

Figure 3-7. Synthetic integration testing

Repeat this for all the major flows for all the combinations of all the APIs you support. It might take a few minutes to execute the tests, but it’ll be well worth the comfort in knowing that the APIs all work well together.

These integration tests should be executed every time code is checked in, as part of your CI/CD pipeline. If integration testing fails, stop everything and fix it.

Authentication

Let’s start with authentication. Authentication ensures that a user, whether a human or another system, is who he/she/it purports to be. It’s like having your ID checked at the airport.

At a high level, your client needs to provide a “secret” of some sort (Figure 3-8). That secret can be a username/password or an API key of some sort, which is typically a long string encoded using base64. Keys are best because they’re easier for developers to use, with many SDKs allowing you to supply the key via a configuration file.

Figure 3-8. Simple authentication flow

Here’s Tesco’s developer documentation for how to pass in a key when making an HTTP GET request for products:

curl -v -X GET "https://dev.tescolabs.com/product/?gtin={string}&
  tpnb={string}&tpnc={string}&catid={string}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

The issue with simply supplying an API key or username/password is that the application now knows your secret. If you have one big monolithic application, it’s fine, as it’s less likely to leak out. But imagine if you have 100 APIs backed by 100 microservices/applications? That creates a whole new set of issues, which we’ll discuss shortly (see Figure 3-9).

Figure 3-9. Don’t let this happen to you!

Authorization

Once you’ve authenticated your client, you must now authorize that client to perform some action, like retrieve an order or query for inventory availability.

Authentication and authorization are often intermingled, but they’re distinct. Going back to the airport analogy, authorization is scanning your boarding pass when boarding your flight. Your identity has already been validated, but now you need to be authorized to board a particular flight.

With one monolithic application backing your APIs, you can put an API gateway in front of your APIs. Begin by cataloging all your APIs and the HTTP verbs allowed by each (POST, GET, PUT, PATCH, and DELETE). Define which groups or individuals are allowed to access each API, and then within each API, which verb they’re allowed to call. This is fairly simple (see Figure 3-10).

Figure 3-10. Securing your APIs through an API gateway

Now let’s say you have 100 separate microservices, each backed by its own application and development team. A vulnerability in any one of those microservices will expose the secret to the public. The secret will need to be regenerated and all clients using it will need to be updated.

OAuth 2 solves this problem by serving as a trusted intermediary between the client and the applications the client is trying to interact with. The client is able to authenticate once with an OAuth server. The server responds with a temporary access token, which the client sends as an HTTP request header with every request. The microservice/application receiving that temporary access token (such as a product or shopping cart microservice), then consults with the OAuth server, asking what rights the token has (see Figure 3-11).

Figure 3-11. Advanced authentication flow

Access tokens are great because they:

• Are temporary

• Can be easily revoked

• Are granular, allowing for fine-grained access to resources

• Don’t force each microservice/application to validate identity, as done by the OAuth server

Most API gateways allow you to define authorization policies, with the underlying implementation and enforcement being left to OAuth 2.

Request Rate Limiting

All your APIs should have throttling in place to ensure that they’re not called too often by any given client, whether maliciously or not. Whether through error or poor architecture, a client can end up calling an API too many times. Establish limits for each type of client. Limit new developers to a thousand requests per hour, for example. But allow your web-based frontend to call your APIs without any limits.

Denial of Service attacks are rampant today. Use your content delivery network or alternate upstream systems to ensure that you’re protected.

If the number of HTTP requests exceeds your policy, respond with an HTTP 429 Too Many Requests response.

Data Validation

As with any application, all inputs must be validated. Since you’re probably using REST APIs, you can use any HTTP-based web application firewall on the market. These firewalls are like traditional network firewalls except that they look more deeply at the HTTP traffic, applying rules that look for malicious behavior, such as cross-site scripting (injecting malicious code that the server then executes), SQL injection (getting the application to arbitrarily execute commands against the database), and the use of special characters or other behavior designed to cause application errors.