In our previous discussions about API design, we outlined an API design strategy, discussed security measures, and the various elements that go into response messages, including search results and links. Now, let’s explore how we can represent actions and metadata in a response message.
Last time we talked about resource response messages. Here, we’ll turn our API design focus towards understanding how to represent search results and links in response messages. To begin, Facebook’s API documentation states that, “Selecting results is not the same as searching.” This is exemplified when we create a language string and query box to search across resource types, whereas when we limit a selection to a specific collection (like photos), you give up the idea of saying give me everything about
One of the most important elements to consider when designing API response messages is which format you’ll use. Most modern apps prefer JSON and this is what we recommend. Only use XML if there's a strong use case to support it. With that said, let’s focus on how to model your response message, for both a single resource and a collection of resources, by looking at how three large APIs do this.
Our previous discussions about API design, which are covered in Web API Design, centered on URL design and we hinted about versioning, errors, and client considerations. Recently, we also outlined an API modeling strategy that’s easy to use. Now we’ll discuss the security measures that you can use to surround your API.
We did a third edition of our webcast on API design, where we drew upon the discussions and implementations with hundreds of crafters and technologists, which helped shape our API design thinking in the twelve months since the previous edition of RESTful API Design. Grounded in the premise that the design of an API communicates how app developers will use it and that the API is an extension of a brand, one of the first topics we tackled in the webcast was API modeling.