CODEWITHSUNDEEP
restapi
heyydrien
heyydrien

Reputation: 981

How do APIs receive the request's method, body, and headers?

The query URL / endpoint below seems to successfully make a request to the API resource and returns a JSON response:

https://wikimedia.org/api/rest_v1/metrics/pageviews/per-article/en.wikipedia/all-access/all-agents/Albert_Einstein/daily/2015100100/2015103100

Given that a request is made up of not only the URL, but also of a method, headers, and body, could someone explain how the API knows which method to use, as well as how the headers and body get transmitted (if they did exist)?

Upvotes: 0

Views: 225

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57267

Given that a request is made up of not only the URL, but also of a method, headers, and body, could someone explain how the API knows which method to use, as well as how the headers and body get transmitted (if they did exist)?

If I'm understanding your question correctly... the API doesn't know these things, the client knows these things.

Which is to say when I'm looking at your question in my web browser, what I'm really looking at is the web browsers interpretation of an HTML document. Because the web browser speaks HTML, it knows what <a href="..."> means; that the quoted text is an identifier for another resource that I the use might want to navigate to.

The browser also knows RFC 3986, so it knows how to parse the quoted string and extract from it the protocol, the host, and the target uri.

Because the browser also knows about https, it knows which port number it should default to when the port isn't specified.

Because the browser knows HTTP, it knows how to construct a valid HTTP request, and the semantics of the required and optional headers it might want to attach.

Because HTTP follows the REST architectural style, we also know that the interface is uniform -- all HTTP resources use the same semantics. So the browser doesn't need to know what the identifier is in order to know that GET, HEAD, OPTIONS are all safe. Similarly, the rules for authentication, caching, content-negotiation, and so on are all the same, so the browser can craft the appropriate headers as it generates the request.

For instance, the browser knows that it is itself HTML capable, so it includes headers that communicate a preference for an HTML or XHTML+xml representation of the resource, if one is available.

Were I to instead switch to the command line, I could use curl(1) to generate the http request instead, which would produce an HTTP request with different headers.

The browser (and curl) know not to send a body with a HEAD or GET request because the HTTP specification explains that the payload of a GET or HEAD request has no defined semantics.

On the API side of the conversation, the server knows about HTTP, so knows how to correctly interpret the bytes of the HTTP request. Thus, the server knows where to look in the request for the HTTP method, the target URI, the headers that may (or may not) modify the context of the request, and so on. The implementation can then do whatever it likes with that information, and construct a suitable HTTP response (in effect, lifting into the headers of the response the metadata in a representation that can be understood by all of the general purpose components participating in the conversation.

Upvotes: 1

Related Questions