Estimate project
← All posts

Is it worth sticking to REST “standards”? The surprise Apple's API had in store for us!

For the most part, REST API design has no formal standard. Beyond the HTTP Spec, all you get are good practices, which you can adopt or ignore.

7 min read
APIRESTRest ApiAPI Design

Introduction

REST APIs are probably the most widespread communication mechanism for public web APIs. Whenever you set out to integrate with a 3rd party service, you can expect to be working with REST. In some cases you will also get SDKs or Open API definitions that make using the API more convenient; in others, all you have is the documentation. Today we’ll look at standards and expectations, as well as at what you can still come across in real-world APIs.

We have recently been working on a project for one of our clients. It involves mobile applications that integrate with payment systems, Apple Wallet among them. Once a purchase is made, the backend validates the transaction – right before granting licenses or virtual currencies for games – to make sure the user actually paid. We began with some research and found the relevant Apple docs, which led us to the right API endpoint. Let’s talk about how it is designed.

Remark: we don’t know the reasoning behind the technical decisions taken while this API was designed. It could be about backward compatibility, a need to integrate with legacy systems, or some other equally important factor. Perhaps it isn’t even meant to be REST, just an “HTTP-API” – all we can do is guess. Still, it is worth noting that other APIs follow a completely different design.

Richardson Maturity Model

As part of this discussion, it’s worth bringing up the Richardson Maturity Model, which splits REST API maturity into four levels. Here is a very brief recap:

  • Level 0 – the base level for a web-based API. Here you might have, for example, a POST /createProduct endpoint.
  • Level 1 – API paths refer to resources. URIs are expected to use nouns instead of verbs, so you’d see paths such as /product/1 rather than /createProduct.
  • Level 2 – HTTP verbs are used in a more standardized fashion – GET for fetching data, POST/PUT for creating, etc. To fetch a product you would call GET /product/1, and to create one, POST /product.
  • Level 3 – HATEOAS (Hypertext As The Engine Of Application State) – the resources returned by the API contain URIs pointing to related resources instead of bare IDs. APIs like this are very uncommon, since without help from additional libraries they tend to be too complex to implement. In our earlier example, the GET /product/1 response would contain links to every related entity, and you could follow them to explore the entire dataset.

Most of the time, the APIs we encounter are at Level 2.

HTTP Verb and endpoint path

Back to the Apple Verify Receipt endpoint. The first thing that catches the eye is the endpoint itself: POST https://buy.itunes.apple.com/verifyReceipt (case sensitive!). Its main job is to verify receipt data (an encoded string sent from the mobile app). Could it be designed in a more RESTful way? Let’s see. The path doesn’t operate on resources (it contains a verb), and we send a POST even though nothing really gets created. In fact, it resembles Level 0.

What would an alternative design look like? That’s not as straightforward as it seems. Starting from scratch, it could be a GET request with a query param – GET, because what we actually do is retrieve a transaction receipt with information about the purchased product. But the encoded receipt data coming from the mobile app can be longer than 6000 characters, while some recommendations say query params should stay under 2048. What else is there? The HTTP 1.1 2014 Specification does in fact permit GET with a body. Sadly, the specification and reality are two different things: plenty of REST client libraries just don’t support it, so that isn’t a great option either. Anything else? We could think about a POST that creates a verification resource – but, once again, nothing is most likely being created under the hood.

How does the competition handle it? Let’s have a look at the Google Play API. Here we find

GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}.

This is clearly more RESTful. The productId and token you pass are far shorter strings than Apple’s receipt data. The key question is what these endpoints actually do behind the scenes – we might guess that Google reads data from a DB, whereas Apple simply decodes the supplied data with a private key. If so, a fair comparison isn’t really possible.

Even though some design decisions may come as a surprise, it’s worth keeping in mind that modeling REST is harder than it might look. Sometimes no single correct answer meets every best practice.

Status codes

What really surprised me about this Apple API were the status codes. The endpoint we looked at returns 200 OK every time. Errors come back in the response body as a status field – 0 stands for valid, and any other value indicates an error. So what happens if you accidentally call GET on that endpoint? 200 OK, with a body containing status 21000. And if you send invalid input (e.g. input that isn’t valid JSON)? 200 OK, with a body containing status 21002. According to the HTTP specs, 200 OK signals that the request succeeded. People debate online whether returning 200 OK with Business errors in the body should be acceptable (the request itself succeeds, only the logic fails), but in my view that’s an entirely different situation from the one here. An illegal HTTP method clearly doesn’t warrant 200 OK.

How does this affect working with the API? It’s certainly not what a developer would expect at first. Some strongly typed REST clients treat 200 OK as success and attempt to deserialize the response into a given format. Such cases can of course be handled, but it takes somewhat more effort than usual.

Note: the GraphQL query language is served over HTTP as well. There, it is common practice to return errors in a predefined body format along with the status 200 OK. Depending on the implementation, though, certain errors may come back with other status codes. As you can see, HTTP can be used in completely different ways depending on the communication protocol, “standards” and practices.

JSON Naming convention

One more thing genuinely made me ask myself: why? Here is what a request body may look like:

{
   “receipt-data”: “...”, …
}

and here is the response:

{
   “status”: 0,
   “is_retryable: …,
   …
}

Spot the difference? Requests use kebab-case, while responses use snake_case. Once again, you can live with it, but some json libraries expect your objects to follow a single casing style. JSON has no standard for key naming – some companies go with snake_case (e.g. GitHub or Zalando), others with camelCase (e.g. other Apple APIs. The choice frequently comes down to the programming language in use.

Authentication

API Security is always a significant subject. There are many ways to authenticate REST APIs, the most common being passing keys in headers. Older APIs sometimes pass keys in query parameters (not recommended) or in the request body – and that’s exactly what happens here: the body includes a password field. Again, not the most typical approach, but one we can accept. It tends to cause more trouble on the backend than on the client side, since the request body must be deserialized before the request can be authenticated. Moreover, if you aim for consistent APIs, what do you do with a GET endpoint, which preferably shouldn’t have a body (see the earlier section on HTTP verbs)?

Conclusions

For the most part, REST API design has no formal standard. Beyond the HTTP Spec, all you get are good practices, which you can adopt or ignore. In my opinion, consistency and high-quality documentation remain the most important factors, as they simply make working with an API easier. Companies attempt to document their guidelines, but as the examples of Zalando, Google Cloud or GitHub show, these can become enormous! Let me repeat it: a REST API is not the easiest thing to design!

When building an API, keep its users in mind. Resources like the Open API specification are extremely helpful – you can use it with Postman or to generate client libraries for chosen languages. A sandbox environment or sample requests that work right out of the box are also great additions that simply make the job easier.

Apple’s verify receipt API design certainly stands out and can be confusing for its users. As noted earlier, we don’t know the reasons behind this design – we can only assume there were good ones.