Recently I was asked to create an APIspecification for one of our company’s projects. Wanting to do it as well as currently possible, I am in the process of deep-diving in all kinds of resources about API building out there. Thing is, right now I feel I know ‘just enough to be dangerous’ and am a bit scared to make bad choices without realising I was making one.
One thing I am currently struggling with, is the fact that many APIstructures are inherently leaky, in the sense that the transport layer (often HTTP) ia also used to indicate the difference between error/success (by e. g. (ab?) using HTTP status codes for this), and giving a semantic meaning to the different HTTP verbs.
Stuff like that directly blocks allowing appiaccess through websockets or something else im the future.
Anyone any tips?
Another thing I am struggling with is the naming of the API actions. Using identifiers in the path is readable as it creates a nice hierarchy, but also feels like complecting task with subject.
Also, send parameters as URL params, inside an x-www/formencoded or as JSON text body?
What about GraphQL? It is transport agnostic, allows tree structure with ease (it is a json superset after all), while also having built-in documentation of the API as well (and Absinthe in Elixir can auto-generate the documentation too, which is awesome!).
I tend to name api actions as verbs though personally.
GraphQL looks very nice, although I get the feeling that it is mostly geared to provide a lot of resources in a user-customizeable way to the public, so I’m not sure if it is suited for the project I am woPAIrking on right now (But it definitely is a great tool I’ll consider in future projects!)
The API I am building has a few Command-calls (that manipulate data or create new resources), and also just a few Query-calls (that retrieve resources).
Turns out that the problems I had (the entangledness/dependentness on using HTTP as transport layer) were mostly with REST-style APIs which, while very prevalent right now, are of course not the only kinds of APIs that exist. JSON-RPC looks like it might solve my problems, since it is transport-agnostic.
Something I do have trouble with, though, is properly naming the API calls in a JSON-RPC specification: In a REST-style API, ‘Semantic URLs’ like GET /users (listing all users), POST /users (creating new user), GET /users/qqwy (fetching info of user with name Qqwy), etc. I have no idea how to make similarly descriptive names without this.
Really, just try Absinthe, once you start with GraphQL it is hard to stop. ^.^
Naming you should just name based on how it works. A GraphQL call is more akin to a function call that can take possible/optional/etc… args and return data, a more pure form of what you are trying now, but you can name them just as you would any other function, just think of it that way.
Take a look at UBER http://uberhypermedia.org, if you want to get an idea about how to design a protocol-agnostic hypermedia type for a REST architectural style. Each resource describes what actions can be performed on it or its relations (append, replace, remove, etc.), which are compatible with HTTP semantics.
json-rpc looks really neat. But you’d still end up naming/namespacing your actions in addition to providing verbs. If it is a simpler api with a few commands, I would really stick to a RESTful API. The http verbs have well defined meanings so you don’t have to reinvent those. As for the naming, you will have to spend some time to think about them. There is always some name which properly conveys the meaning of your action. Take logging in and logging out for instance. The common verbs and path for this are login => POST /sessions, logout => DELETE /sessions.
