3 Ways to Make Your API Beautiful

Building an API is a lot like building a toilet.
If you're not sure the experience is easy for the people using it, you're doing something wrong.

The phenomenal book Web API Design: The Missing Link has inspired me to post my key takeaways about what makes an API great.

Use Links In Your APIs

APIs with links save Application Developers time reading through documentation to understand how to retrieve data.
Imagine for a second that you're an application developer using the Game of Thrones API. No spoilers here! (Some judgement though).

The data looks something like this:

// The actual API uses links. This has been edited to show my point.
// I also removed any possible spoilers for you :)

{
 "id": "583",
 "name": "Jon Snow",
 "gender": "Male",
 "culture": "Northmen",
 "born": "In 283 AC",
 "father": "2342",
 "mother": "1243",
 "spouse": "4553",
 ...,
 "playedBy": [
  "Kit Harington"
 ]
}

You want to build a website that maps all Game of Thrones characters and their relationships, but in order to do that, you have to check the documentation for the URI template to build a URL for the resource with id "2342", "1243", "4553", …

This clearly isn't ideal.

If the API Developer had instead used links when modeling their data, the application developer wouldn't have such a hard time using the t̶o̶i̶l̶e̶t̶ API.

This is a much better pattern.

{
"id": "https://anapioficeandfire.com/api/characters/583",
"name": "Jon Snow",
"gender": "Male",
"culture": "Northmen",
"born": "In 283 AC",
"father": "https://anapioficeandfire.com/api/characters/2342",
"mother": "https://anapioficeandfire.com/api/characters/1243",
"spouse": "https://anapioficeandfire.com/api/characters/4553",
...,
"playedBy": [
"Kit Harington"
]
}

Now the application developer can write general-purpose code to
follow API links without having to comb through the docs.

Query URLs Should be Predictable

There are plenty of places to inject creativity into your
programming, but query URLs are not one of them.

Which query URL pattern is easier for you to remember?

Option A:

https://dogtrackercom/person/{personId}/dogs

or Option B:

https://dogtrackercom/getPeopleFunction/{personId}/getAlldogs

In addition to being easy to remember, Option A more clearly demonstrates the relationship between the person entity and the dog entity.

Designing a query language specific to your API can be helpful to you during development, but it makes it much harder to use your API.

Give Developers Only What They Need

APIs that return large collections of objects must provide a way for clients to retrieve smaller subsets of the collections at a time. These APIs need pagination.

I'm more likely to retain users if my application calls the API that returns 100 pictures of puppies in .083 ms than I am with the API that returns 1000000 pictures of puppies in 2.32 s.

It's common for APIs to follow a pattern of pagination like this:

{
self": "https://dogtracker.com/dogs?limit=25,offset=0",
"kind": "Page",
"pageOf": "https://dogtracker.com/dogs",
"next": "https://dogtracker.com/dogs?limit=25,offset=25",
"contents": [
{"self": "https://dogtracker.com/dogs/12344",
"kind": "Dog",
"name": "Fido",
"furColor": "white"
},
{"self": "https://dogtracker.com/dogs/12345",
"kind": "Dog",
"name": "Rover",
"furColor": "brown"
},
… (23 more)
]
}

Where "pageOf" represents the original collection, "next" references the page after, and "previous" describes the page before (previous is missing in this example because it is the first page).
The "offset" and "limit" parameters allow the application developer to request the amount of resources they need at a time. "Offset" defines the starting point, and "limit" defines desired the number of objects.

Additionally, it can be useful to have optional fields that developers can use to retrieve only the information they need about a resource.

https://dogtracker.com/dogs?fields=name,color,location

This will retrieve only the names, colors, and locations of all dogs.

Wrapping Up

In conclusion, whether you are designing a toilet or an API, it is important to make the job as easy as possible on the people who will be using it.
Standardize things as much as possible.

TLDR:

Use Links in your APIs
Standardize your query templates
Make Pagination easy

If you enjoyed this, be sure to like the post and follow me for more content on APIs, Software Development, and more!