Request for Comments: New API Design Concept [pdf]

https://origami.ink/rfc_new_api_design.pdf

2 3 2 years ago

I need input on this new API design, i call if 'Functional APIs(fAPIs)'

Given that hacker news is mostly developer-oriented i would like your opinion as to why we don't use "HTTP APIs" as mostly single functions instead of the REST and GraphQL horrors i see on a weekly basis.

why not:

https://example.org/api_json_create_new_user

body -> { 'name': 'new user' 'email': 'email@gmail.com' 'password_hash': '50e721e49c013f00c62cf59f2163542a9d8df02464efeb615d31051b0fddc326' ... }

200 OK

instead of

https://example.org/v1/users/create/new <body>

200 OK

i attached a PDF link with more details.

criticism is welcomed.

MissTake• 2 years ago

Not seeing any value in this myself. Seems to be difference for difference sake, but I fail to see what it really brings to the table.

You start off with a ‘complex’ JSON but there’s absolutely nothing in the PDF that describes how this fApi is meant to address that.

Also not seeing any real justification as to the actual real need for this, other than “it’s different”.

Finally the claim that the versioning is somehow better, to me is the exact opposite. By having the version number at the start it makes it easy to switch between versions without having to append to a “function name”.

Sorry, but it’s an absolute hard-pass from me. As it stands I fail to see any value whatsoever in this over RestAPI.

Dog knows I’m no fan of GraphQL, but I’d take that over this any day of the week and twice on a Wednesday…

pledess• 2 years ago

For example, GET /tickets/12/messages/5 has these advantages over api_get_message_from_ticket?ticket_id=12&message_id=5

Avoids writing everything twice: you don't need to name the data fields both in the base URL and in the query string

If there are several parameters, writing everything twice may make the URL longer than one physical line in a text editor

The ? and & characters need to be quoted in most shells

The _ characters are sometimes hard to read if the entire URL is underlined

Names with api_json don't make it clear whether the request body must be sent as JSON, the response will be JSON, or both

Request for Comments: New API Design Concept [pdf]

Related Stories