Tohuwabohu excorcism

User Tools

Site Tools

Trace: • start • togaf • kinesis • aws • big_data • azure-foundational • beats • android • apigateway • rest
rest

This is an old revision of the document!

Table of Contents

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
Safex
Idempotentxx 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>

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.

Request: 

GET /slots/?status=open&doctor=mjones

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>
HTTP/1.1 409 Conflict

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

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

Request 

POST /slots/1234 HTTP/1.1

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

Response 

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>

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"
		}
	}
	
}
rest.1519829678.txt.gz · Last modified: (external edit)