Why build a non-RESTful API

One of the most common architectural styles to build an HTTP API is RESTful, or just REST, it works great for generic and open API that will be used used by many different clients, another common one is GraphQL, created by Facebook.

When building an open API following one of those, or both as like GitHub, is the best idea, both are standard which will help other to intuit how your API works.

However, when building an internal API for a product, you don't need to support many clients, you only need to support a few, and you control them.

Actually, building a generic API could make you slower and force you to do more work Client-side, imagine you are building a new route for your application, in this route you will show three different resources, most of the time you will need to trigger three different requests to get all the data, instead, in you don't strictly follow REST you will be build a custom endpoint for that view, this endpoint will directly read from the DB at the same time, all the data you need, this is way faster than doing three individual requests, at the end you request only one endpoint and can get all the resources you need.

The same could happen when performing a mutation, you could expose custom endpoint for the different actions an user may perform against the data (e.g. /api/me/upload-avatar) and be more specific, this could let you optimize them more than creating a generic PATCH /api/users/:id endpoint.

If you think this looks like RPC, or even GraphQL, yes that's exactly the idea, with GQL you can easily run a single query to get all the data a route will need, additional data could be later fetched when needed of course, but the idea is to reduce the number of requests you do and receive only the data you will need. For mutations, both use specific names instead of a generic endpoint used to any mutation.