This is an old revision of the document!

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:
http://www.se.uni-hannover.de/pub/File/kurz-und-gut/ws2011-labor-restlab/RESTLab-HTTP-Serhat-Esen-kurz-und-gut.pdf

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	Creates a concrete resource, which will be a CHILD of the given URL. POST http://api.ex.com/tales/7dwarfs/ {name=oink..}
PUT	Creates a concrete resource, which will be reachable under the GIVEN CONCRETE URL. PUT http://api.ex.com/tales/7dwarfs/oink {name=oink..}
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”

compare REST vs just some HTTP based interface

What makes REST different from SOA or HTTP-based interfaces

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:

POST /appointmentService HTTP/1.1
[various other headers]

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

Response:

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>

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.

Request:

POST /doctors/mjones 
[various other headers]

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

Response:

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>

Request:

POST /slots/1234 

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

Response:

HTTP/1.1 200 OK

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

3. 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.

Request:

GET /doctors/mjones/slots/

Response:

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>

Request:

POST /doctors/mjones/slots/

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

Response:

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>

REST API Example

High level Structure

The structure of the responce:

errors

data
   attributes
   links
      self
      related
   relationships
included
meta

Responses

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"
		}
	}
	
}

Tohuwabohu excorcism

Table of Contents

REST - Representational state transfer

Methods

compare REST vs just some HTTP based interface

What makes REST different from SOA or HTTP-based interfaces

0. Swarm of POX - Plain old XML

1. Resources

3. Using HTTP Verbs

REST API Example

High level Structure

Responses