Memo: REST and RPC

Memo: REST and RPC.md

REST

Representational state transfer

---

Source:

• REST - Wikipedia
• Roy Fielding's dissertation

Links:

• OpenAPI

---

RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations

• Client-Server: Separation of concerns is the principle behind the client-server constraints.
• Stateless, session state is therefore kept entirely on the client.
• Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable.
• Uniform Interface: implementations are decoupled from the services they provide
• Layered System allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot "see" beyond the immediate layer with which they are interacting
• Code-On-Demand allows client functionality to be extended by downloading and executing code in the form of applets or scripts.

Request methods

See Wikipedia and MDN web docs

GET

Examples: Get github webhook

$ curl -sH "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxx" \
https://api.github.com/repos/<user>/<repository>/hooks/<id> | jq
{
  "type": "Repository",
  "id": 146058386,
  "name": "web",
  "active": true,
    ...
}

$ curl -s https://galaxy.ansible.com/api/v1/platforms/ | jq '.results | group_by(.name)[] | {key: .[0].name, length: length}'
{
  "key": "AIX",
  "length": 3
}
{
  "key": "Alpine",
  "length": 1
}
{
  "key": "Amazon",
  "length": 6
}

• HEAD, identical to former, however without response body
• POST, the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the uri
• PUT request that the enclosed entity be stored under the supplied uri
• DELETE deletes the specified resource.
• TRACE echoes the received request so that a client can see what (if any) changes or additions have been made by intermediate servers.

OPTIONS

returns the http methods that the server supports for the specified url.

curl -X OPTIONS http://example.org -i

• CONNECT converts the request connection to a transparent tcp/ip tunnel
• PATCH applies partial modifications to a resource

CLI

curl

curl is a command-line tool for transferring data and supports about 22 protocols including HTTP, it supports over 200 command-line option

-v  verbose
-o  output
    redirect STDIN to ouput

GraphQL

https://developer.github.com/v4/guides/migrating-from-rest/

RPC

https://etherealbits.com/2012/12/debunking-the-myths-of-rpc-rest/