There are not many people who I trust on the subject of API design like I do Phil Sturgeon. He has been a prominent speaker both online and at numerous conferences, covering a variety of problems, solutions, and approaches in the API design domain.
In one of his recent blog posts, he shared a diagram (see above) which provides a clear illustration on which API paradigm – REST, GraphQL, or RPC – one should pick for a web application, based on a variety of criteria.
I think this is probably the simplest of all the explanations I’ve seen around.
I’ve been working with REST/RESTful APIs for a while now. They are usually a lot better than the SOAP or XML-RPC stuff we had before. But they are also not perfect. Error handling and reporting is a common area between many implementations that needs more attention and consistency. Turns out, there is, I’ve just somehow never heard of it – RFC7807 defines “Problem Details for HTTP APIs”.
I’ll need to look more into this and see if and how it is better than a variety of things I’m using now. Gladly, there is even a PHP library to help with that – Crell/ApiProblem:
This library provides a simple and straightforward implementation of the IETF Problem Details for HTTP APIs, RFC 7807.
RFC 7807 is a simple specification for formatting error responses from RESTful APIs on the web. This library provides a simple and convenient way to interact with that specification. It supports generating and parsing RFC 7807 messages, in both JSON and XML variants.