If you are going to expose a user interface to customers and call a back-end from the front-end, it’s an API. Now you may not think of your application as an API or a browser as an API client, but you are exposing a surface that consumers could call outside of the intended use cases.
Having an undocumented API is both a security risk on your side if it’s not evaluated for public consumption and a frustration for clients.
APIs should consistently represent entities and classes across requests. This means both that discrete units of data / content should be represented the same way, no matter what method using to retrieve them, but that endpoints should only return one type of entity.
For example, when getting an entity directly, it should return the same data as when the entity is returned from search. Finally, entities should have consistent identification, sometimes using a GUID vs numeric identifier vs who knows what else across methods makes it harder for clients to understand how to retrieve an entity across methods.
Not having a consistent representation of entities and classes makes it harder for clients to work with and understand the API as well as introducing more complexity on both the client and server side to represent all of the variations.
All this being said, entities can be logically sub-typed and containing sub-entities.
Sub-types enable APIs to represent commonalities across multiple types.
For example, you could have an endpoint which returns content. This content could include documents and assets, each of which would have different data, however both share a common set of file data and must have a clear distinction between the document and asset sub-types.
Sub-entities enable APIs to represent discrete groups of data and functionality as a part of a larger entity.
Going back to the file example, you could have sub-entities to represent the publication state, metadata and binary representation of the file to enable interacting with the aspects of the file without having to consider unrelated data and operations.
As an API client, you really want to be sure you know what every call is going to do. An API which presents incoherent operations makes this much harder. Incoherency here means that the name or method of an operation doesn’t match what it does.
Examples of incoherent operations include:
Do not get me wrong, you must document your API. But an API is like a joke, if you need to explain it, it’s not good.
Developers should be able to start using an API after reading a getting started document. Over-reliance on documentation versus consistency increases the mental load on developers, much less if you have to read a small novel to understand an API.
What can you not abide in an API? Leave a comment below with your thoughts!