====== REST - Representational state transfer ======

===== Methods =====

Dies ist eine Konvention (kein Standart) zur Anfrage der Daten via HTTP.
Es werden Methoden übergeben:

|          | GET | POST | PUT | DELETE| PATCH|
|Safe      |  x  |      |     |       |      |
|Idempotent|  x  |      |  x  |  x    |      |


Idempotence means that executing the funciton more than once has the same effect as if I would execute it more than once.

A good describtion is here: \\
https://restfulapi.net/idempotent-rest-apis/


|GET| Just retrieves the resource, without changing it.|
|DELETE| Removes a concrete resource. When repeated - does the same. So resources does not exist after removal.|
|POST| <WRAP>Creates a concrete resource, which will be a **CHILD** of the given URL.  <code>POST http://api.ex.com/tales/7dwarfs/ {name=oink..}</code></WRAP> |
|PUT| <WRAP>Creates a concrete resource, which will be reachable under the **GIVEN CONCRETE URL**. <code>PUT http://api.ex.com/tales/7dwarfs/oink {name=oink..} </code></WRAP> |
|PATCH| Changes the resource. The change may define the required state, which makes it NON idempotent. From Name=John to Name=Gargantua. After repeated applying the name will be Gargantua and patch will fail, since it should change "from Name=John" |



===== Maturity of REST ======
{{https://martinfowler.com/articles/images/richardsonMaturityModel/overview.png}}


==== What makes REST architecture mature? 4 steps ====
https://martinfowler.com/articles/richardsonMaturityModel.html

=== 0. Swarm of POX - Plain old XML ===

Characteristics:
  * exchanging some XML / JSON with **some Service like /appointmentService**
  * tunneling a mechanism for an own RPC - remote interaction mechanism

Request:
<code>
POST /appointmentService HTTP/1.1
[various other headers]

<openSlotRequest date = "2010-01-04" doctor = "mjones"/>
</code>

Response:
<code>
HTTP/1.1 200 OK
[various headers]

<openSlotList>
  <slot start = "1400" end = "1450">
    <doctor id = "mjones"/>
  </slot>
  <slot start = "1600" end = "1650">
    <doctor id = "mjones"/>
  </slot>
</openSlotList>
</code>



=== Glossary === 
| Compound Documents | <WRAP> 
To reduce the number of HTTP requests, servers MAY allow responses that include related resources along with the requested primary resources. Such responses are called “compound documents”.
https://jsonapi.org/format/#document-compound-documents 
</WRAP> |
|Sparse Fieldsets| A client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter. <code>GET /articles?include=author&fields[articles]=title,body&fields[people]=name`</code> |





=== 1. Resources ===

Characteristics:
  * tunneling a mechanism for an own RPC - remote interaction mechanism. **But to special URIs** - not one service.
  * **using Resources**. On the URI too like **/doctors/mjones** or  **/slots/1234/appointment**. Collections are for listing resources. Concrete resources are for getting details. \\ Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.

Request:
<code>
POST /doctors/mjones 
[various other headers]

<openSlotRequest date = "2010-01-04"/>
</code>

Response:
<code>
HTTP/1.1 200 OK
[various headers]


<openSlotList>
  <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/>
  <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"/>
</openSlotList>
</code>


Request:
<code>
POST /slots/1234 

<appointmentRequest>
  <patient id = "jsmith"/>
</appointmentRequest>
</code>

Response:
<code>
HTTP/1.1 200 OK

<appointment>
  <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/>
  <patient id = "jsmith"/>
</appointment>
</code>


=== 2. Using HTTP Verbs ===
Characteristics:
  * tunneling a mechanism for an own RPC - remote interaction mechanism. **But to special URIs** - not one service.
  * **using Resources**. On the URI too like **/doctors/mjones** or  **/slots/1234/appointment**. Collections are for listing resources. Concrete resources are for getting details.
  * **Using GET, POST, PUT, DELETE, PATCH - similarly to HTTP**. GET is safe. POST, DELETE, PATCH are not. \\ Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.



Request:
<code>
GET /slots/?status=open&doctor=mjones
</code>

Response:
<code>
HTTP/1.1 200 OK

<openSlotList>
  <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/>
  <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"/>
</openSlotList>
</code>



Request:
<code>
POST /doctors/mjones/slots/

<slot>
  <slot patient="john doe" status="confirmed" doctor = "mjones" start = "0800" end = "0950"/>
</slot>

</code>

Response:
<code>
HTTP/1.1 200 OK

<openSlotList>
  <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/>
  <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"/>
</openSlotList>
</code>



<code>
HTTP/1.1 409 Conflict

<openSlotList>
  <slot id = "5678" doctor = "mjones" start = "900" end = "1000"/>
</openSlotList>
</code>




=== 3. HATEOAS - Hypermedia As The Engine Of Application State ===

Characteristics:
  * tunneling a mechanism for an own RPC - remote interaction mechanism. **But to special URIs** - not one service.
  * **using Resources**. On the URI too like **/doctors/mjones** or  **/slots/1234/appointment**. Collections are for listing resources. Concrete resources are for getting details.
  * **Using GET, POST, PUT, DELETE, PATCH - similarly to HTTP**. GET is safe. POST, DELETE, PATCH are not.
  * The **references** to **next steps** are **embedded dynamically** into the response. Allowing to develop the client separately from the server. It allows the server to change its URI scheme without breaking clients. https://ru.wikipedia.org/wiki/HATEOAS \\ Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.

Request
<code>
POST /slots/1234 HTTP/1.1

<appointmentRequest>
  <patient id = "jsmith"/>
</appointmentRequest>
</code>

Response
<code>
HTTP/1.1 201 Created
Location: http://royalhope.nhs.uk/slots/1234/appointment

<appointment>
  <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/>
  <patient id = "jsmith"/>
  <link rel = "/linkrels/appointment/cancel"
        uri = "/slots/1234/appointment"/>
  <link rel = "/linkrels/appointment/addTest"
        uri = "/slots/1234/appointment/tests"/>
  <link rel = "self"
        uri = "/slots/1234/appointment"/>
  <link rel = "/linkrels/appointment/changeTime"
        uri = "/doctors/mjones/slots?date=20100104@status=open"/>
  <link rel = "/linkrels/appointment/updateContactInfo"
        uri = "/patients/jsmith/contactInfo"/>
  <link rel = "/linkrels/help"
        uri = "/help/appointment"/>
</appointment>
</code>



==== HAL - Hypertext Applicaiton Language ====

**REST** is a concept of application architecture. Its multiple maturity states are defined above: Stack of POX, Ressource, Verbs etc.


**HATEOAS** is a concept of application architecture. It defines the way in which application clients interact with the server, by navigating hypermedia links they find inside resource models returned by the server.

To implement HATEOAS you need some standard way of representing resources, that will contain hypermedia information (links to related resources), for example, something like this:


**HAL** is one of such standards. It is a specific format of resource presentation, that can be used to implement HATEOAS.


  * HAL Introduction: http://javaeeeee.blogspot.ch/2015/02/introduction-to-hypertext-application.html
  * HAL browser: http://api.m.ox.ac.uk/browser/#/

===== REST API Example =====

==== High level Structure ====

The structure of the responce:

<code>
errors
</code>

<code>
data
   attributes
   links
      self
      related
   relationships
included
meta
</code>


==== Responses ====

<code>
GET http://api.ex.com/tales/7dwarfs/1
{
	data{
		id: 1,
		type: characters,
		attributes{
			name: "oink",
			size: "1m",
			race: "dwarf"
		},
		links{
			self: "http://api.ex.com/v1/tales/7dwarfs/characters/1"
		}
	}
}


GET http://api.ex.com/tales/7dwarfs/8
{
	data{
		id: 8,
		type: characters,
		attributes{
			name: "snowwhite",
			size: "1.7m",
			race: "human"
		},
		links{
			self: "http://api.ex.com/v1/tales/7dwarfs/characters/8"
		}
	}
}

GET http://api.ex.com/tales/7dwarfs/
{
	data{
		id: 7dwarfs,
		type: tales,
		attributes{
			name: "7 dwarfs"
		},
		links{
			self: "http://api.ex.com/v1/tales/7dwarfs"
		},
		relationships{
			housekeeper: {
				data: {
					id: 8,
					type: "characters",
				},
				links: {
					self: "http://api.ex.com/v1/tales/7dwarfs/relationships/housekeeper",
					related: "http://api.ex.com/v1/tales/7dwarfs/characters/8",
				}
			}
		}
	}
}

GET "http://api.ex.com/v1/tales/7dwarfs/characters?limit=5;offset=5",
{
	data: {
		characters:	[
			{ id:6, name: "gloink" }
			{ id:7, name: ".." }
			{ id:8, name: "snow white" }
			{ id:9, name: ".." }
			{ id:10, name: ".." }
		],
		links: {
			first: "http://api.ex.com/v1/tales/7dwarfs/characters/1",
			prev: "http://api.ex.com/v1/tales/7dwarfs/characters?offset=0;limit=5",
			next: "http://api.ex.com/v1/tales/7dwarfs/characters?offset=10;limit=5",
			last: "http://api.ex.com/v1/tales/7dwarfs/characters/25"
		}
	}
	
}

</code>


== CURIES ==
Cut URI - an approach to reduce the long URLs

<code>
GET http: //api.ex.com/tales/7dwarfs/1{
	data{
		id: 1,
		type: characters,
		attributes{
			name: "oink",
			size: "1m",
			race: "dwarf"
		},
		curies{
			{
				name: "root",
				href: "http://api.ex.com/v1/"
		},
		links{
			self: "root:tales/7dwarfs/characters/1", 
			prev: "root:tales/7dwarfs/characters/0", 
			next: "root:tales/7dwarfs/characters/2", 
		}
	}
}
</code>