loading...

What are differences (in API) with payload being inside path params, querystring and body?

patarapolw profile image Pacharapol Withayasakpunt ・1 min read

Also,

  • Where did hashes go?
  • Would you use querystring inside POST, PUT, and PATCH?
  • What about OPTIONS? Can it read querystring and body?

Discussion

markdown guide
 

From RFC 7230 Section 2.7

http-URI = "http:" "//" authority path-abempty [ "?" query ]
                [ "#" fragment ]

Specifically about the components, we can read RFC 3986

Path

The path component contains data, usually organized in hierarchical form, that, along with data in the non-hierarchical query component (Section 3.4), serves to identify a resource within the scope of the URI's scheme and naming authority (if any).

Query

The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource within the scope of the URI's scheme and naming authority (if any).

So I'd say in an API, path params are for hierarchical parameters, such an id parameter under user, while query parameters are for non-hierarchical parameters, such as search filters.

About body (RFC 7231 Section 4.3.1):

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.


Fragment (Hash) from RFC 3986 Section 4.2

Fragment identifiers have a special role in information retrieval systems as the primary form of client-side indirect referencing

RFC 7231 Section 9.5

fragment identifiers used within URI references are not sent in requests


There is nothing against using query in POST, PUT, and PATCH. However, PUT and PATCH are explicitly defined in terms of a body payload:

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. (RFC 7231)
The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a "patch document" identified by a media type. (RFC 5789)


OPTIONS from RFC 7231 Section 4.3.7

A client that generates an OPTIONS request containing a payload body MUST send a valid Content-Type header field describing the representation media type. Although this specification does not define any use for such a payload, future extensions to HTTP might use the OPTIONS body to make more detailed queries about the target resource.

It can read query and body, but there is no standard on the semantics.