I recently presented at APIWorld about how API definitions go beyond the payload specification into providing details of terms and conditions and so on. You can see the presentation here (more about my presentations here).

One of the questions during the presentation did I have other examples of good APIs, reflecting the points I’d made. A very valid question, to which I didn’t have more examples to hand, hence this post.

So the easy answer would be to point to an excellent article on Nordic APIs (here) that address the question and explain why they rate the APIs. But that’s a little bit of a lazy answer and in all fairness, the examples provided are from organisations where APIs are recognised as a primary or important contributor to business revenue. So I’ve looked at areas where the API may not necessarily be seen by the business as the primary source of revenue. With the examples provided, we’ve described what we think is good, or not so good about them. Hopefully, through these examples, you’ll see why points are made in the presentation. So here are my reviews…

Walgreens (Developer Portal)

Walgreen’s in the US provide a number of APIs to several services such as photo printing. This has allowed app developers to send photos from a smartphone direct to a store to be printed.

The developer site has a strong self-service capability, even if though aspects of this are handed off to 3rd parties. The terms and conditions for some of this aren’t so clear. There is plenty of information about the services and expectations for data such as photo images.

Ironically the payload information itself is weaker than it could be, some operations that would be assumed to GET are POST. The definition of the JSON attributes to call Walgreens are described but not the return values. Constraints like rate limiting are published. But the steps to use APIs are laid out, and code samples for multiple languages.

A Postman Collection for printing photos exists, but other API services arent covered.

NOTE: Since writing this, the Portal site https://developer.walgreens.com/ has been returning with a 502 Error

Oracle Hospitality (OHIP)

Oracle Hospitality as they moved to a SaaS model gave the need to overhaul integration mechanisms. The hospitality suite is substantial with 3000 APIs. The services are biased towards B2B rather than B2C.

The API documentation is pretty complete from the documentation reviewed – there are 3000 APIs across the entire suite. To support activities such as integrating hotel staff HR solutions through to migrating with 3rd party door card-key systems. Consuming the documentation is impacted by the fact that it is forced to fit into Oracle’s wider content management which doesn’t lend itself well to embedding other solutions like GitHub, Postman and Apiary.

The use of Apiary is particularly effective, as it provides very dynamic documentation, test endpoints, code fragments for different languages (but not an SDK in the sense of easing the process of connections etc). For example the Cloud Activity API and the full list of Apiary documents here. In addition that there are Postman Collections (more here) that show common use cases of API use with supporting documentation.

There are a few small quibbles if you want to nitpick. Some key identifiers appear to be redefined rather than using a shared definition. The way dates should be used could be clarified, will they be month-day (i.e. US format) or day-month (as done by countries like the U.K.).

Mercedes Benz (Developer)

Mercedes vehicles are at the prestige end of the market, and competition is moving manufacturers to provide nice features that can be delivered through people’s smartphones. Given the sensitivities around potentially having features hijacked for the purposes of vehicle theft, it is surprising (but also rather pleasing) to see that at least some aspects of the cars are visible to APIs. The Developer site also provides APIs for a range of other potential uses including image catalogues, a car builder and other such services – empowering dealers to use their own apps.

Looking at the APIs around the car (requires registration). The documentation is rich in content, providing information not only about the API but likely use cases. With this, they’ve provided information about how to access, what is provided for different tiers of use. Although exact charges are not listed (presumably until you register a project with Mercedes).

The authentication mechanisms are well documented – important given my point around security. Looking at the car status API, the API documentation is rich and clear. No test endpoint, rather the live system can be used with synthetic vehicle identities which is a nice touch. The values provided and returned are not described in all cases, but we found plenty of examples detailing the return values. One point of criticism is that all data values are treated as strings, even when the documentation elaborates that the values are numeric or could be shown as enumerations. If this was restricted to one aspect I’d say I was nitpicking, however, every attribute is like this.

The site provides example requests and responses, with good use of HTTP response codes. The examples only use CURL and don’t offer code fragments to help and no evidence of an SDK. The documentation does reveal some behind the scenes implementation details for the push service (see comments here about Kafka), not something we’d recommend but necessary as Mercedes allow you to connect to specific topics. Code examples in this area are provided on GitHub.

Service status and updates on availability are accessible and associated API status information is linked to the API status which is a nice touch (you can see the general status link at the bottom of the screenshot.

Conclusion

While none of these examples is perfect, the Mercedes and Oracle OHIP examples are certainly very good for different reasons. Oracle’s OHIP APIs are very developer-friendly, technically strong (unsurprising as the Product Director in this space has contributed and written books on APIs – see here) and Mercedes as you might expect has a very good user experience with the use cases, everything within the one site. Bring these together and the chances are you’re APIs will feature in a future Nordic APIs article.