When developing an API, one of the first critical decisions every developer must face is that of Content Type. In this day and age most APIs return one or both of JSON or XML.
photo by Sean Svadilfari
Some APIs get away with one, and that’s fine, but to improve the UX of your API, you should allow the requestor to determine what data type is best for them. If you’ve read the post on API Content Negotiation, you’ll know the best way to approach content negotiation is to follow the standards.
What exactly is Content Negotiation? According to Wikipedia it’s “a mechanism defined in the HTTP specification that makes it possible to serve different versions of a document at the same URI, so that user agents can specify which version fit their capabilities the best”.
photo by JD Hancock
So, it serves two purposes: (1) making it possible to have different versions of the same response, and (2) letting clients specify which version they want to receive. Usually, this technique is applied when there are several types of user agents consuming the same HTTP resource but, because they have different rendering capabilities, they might ask for different content types.
One of the biggest difficulties developers can have when writing code that talks with an API is dealing with errors and exceptions, and translating those errors into something meaningful for their applications.
photo by Bent Jensen
Because APIs are based on different technologies and libraries, error codes are often inherited and do not make sense to whatever framework the consumer is using. Even worse is when those error codes and messages are simply passed through to the end-user without any manipulation by the application.
So, how can you make sure that all your API consumer understand your error codes and can handle them properly? If you’re offering a REST API, consumers expect your endpoints to behave like any other HTTP endpoint, so a good start is to simply follow the standards.