Add JSON requests instead of URI requests

[dorsax]

Modern REST-APIs do not use URI requests, meaning that an URI is appended by PHP-Flags. As URIs are almost always somehow logged and users tend to use HTTP over HTTPS any confidential data would be visible to anyone on the same network, this is no longer the as-is-Standard. Instead, a call should be made by calling an Endpoint with the correct payload, containing a JSON object specifying anything relevant to the endpoint.

This brings several nice and easy features:

1. Security
2. Ease of Expansion (i.e. new features in an endpoint only need appending the JSON)
3. Developing requests in Websites, Plugins or even other programs is done by following standards for making REST-calls

Please consider this before adding authentication for services like requested in #8

[jacobsandersen]

I didn't know GET supported JSON payloads.

E: at least not semantically

E2: of course any private information would be using a different request method (such as POST) and as such would be accepting a JSON payload in the request body, we would never do this via URL

[md-5]

Sorry what? I don't understand what you're getting at. GET is a standard part of REST....

[dorsax]

@md-5 of course, it is a standard Request Word of HTTP. The current API version requires to add parameters as part of the URI though instead of sending them in the request body as a JSON-object. This is considered best practice because of reasons mentioned in the issue.

[md-5]

GET doesn't have a request body, I have no idea what you're on about https://stackoverflow.com/questions/978061/http-get-with-request-body https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET

[dorsax]

Having no semantics does not mean it is impossible, but it means that some services may have done the wrong thing in the past. As the Answer on Stack Overflow shows very good, the first RFC said you don't need a body, some developers read it as they can't have bodies, which was revised in the latest RFC 7231:

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

That's why you can and should use a GET body. If you use nginx or Apache2 or IIS in the latest versions, you can handle them and most common languages like java or Python3 can handle them, too. The only usecase where this could be satisfying not to use is if a person would like to use the API in their browsers. However, that's what the website is for.

[jacobsandersen]

@dorsax Can you provide some literature supporting the claim that when using the standard GET request method that we should be using request bodies (which have no semantic meaning to GET) over GET parameters (the known standard)?

If you can provide these, we can have a more productive discussion. As of right now, all I am able to ascertain is that this is a style suggestion and not an actual nod to a new standard (please correct me if this isn't right).

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

Sorry, but this doesn't do it for me. The first clause says there are no semantics, and the second clause supports the first by saying that sending a request body may cause the service to reject the request.

They'd reject the request because the request was not following the semantic definition of GET (which is that request bodies have no semantic meaning to GET). That makes sense to me. It does not seem to suggest that we should be moving toward handling request bodies while using GET.

As previously mentioned, we will (without question) use request bodies and proper standards while handling any private information. That said, however, for API keys there are numerous examples in the real world of those being accepted via URI. However, more likely, we will require it as an HTTP header. This would not go into the request body. Any other parameters are for reading only, and do not/would not represent any private information so we would be using GET + Header.

Like I said, get back to me if you wish to continue discussing this. I'm open to hear your side, but I'm not convinced at the moment.

[dorsax]

Hey @simpleauthority I had a deep dig into my past projects where I called different REST APIs to get a better personal overview because I started to doubt myself. In my "study" I got the following results:

• any API w/o authentication uses GET with URI parameters
• any API with authentication uses POST request with JSON bodies
• mixed APIs apply the URI parameters in GET, POST uses JSON body

I have to admit I was biased from the beginning and I know now why. First, the latest project I am working on uses a closed source API (documentation isn't publicly available, too), where even GET uses a request body. Second, almost any APIs I used in the past year had authentication, and I almost exclusively worked with those parts. It seems like I assumed that a Request Body was the de facto standard because of this bias.

I also want to admit that I came here with the authentication part in mind and didn't explicitly wanted GET with a request body. I just assumed it was a standard, which I have now proved myself to be wrong. Somehow I was triggered after the first message of @md-5 because it wasn't very constructive but rather destructive to me. I want to apology for the mess. Thank you for your work on an API, all devs can benefit from that :)

[md-5]

None of the apis in this project have authentication....