1

Anton Bogdan◦ Architect in Softengi company

◦ Enviance team

29 years old

2

Representational

State

Transfer

3

is a software

architectural style

2000 by Roy Fielding in his doctoral dissertation at UC Irvine

4

Client–server

Stateless

Cacheable

Layered system

5

Uniform interface◦ Identification of resources (URI)

◦ Manipulation of resources through these representations

◦ Self-descriptive messages

◦ Hypermedia as the engine of application state (A.K.A. HATEOAS)

6

Then you will get:

Performance, scalability, simplicity, modifiability, visibility, portability, and

reliability.

7

8

9

POST /appointmentService.asmx◦ <openSlotRequest date = "2010-01-04" doctor =

"mjones"/>

HTTP/1.1 200 OK◦ <openSlotList>◦ <slot start = "1400" end = "1450“ status=“open”>◦ <doctor id = "mjones"/>◦ </slot>◦ <slot start = "1600" end = "1650“ status=“booked”>◦ <doctor id = "mjones"/>◦ </slot>◦ </openSlotList>

10

POST /doctors/mjones/appointments/◦ <openSlotRequest date = "2010-01-04“/>

HTTP/1.1 200 OK◦ <openSlotList>

◦ <slot start = "1400" end = "1450“ status=“open”/>

◦ <slot start = "1600" end = "1650“ status=“booked”/>

◦ </openSlotList>

11

GET /doctors/mjones/appointments/?date=20100104

HTTP/1.1 200 OK◦ <openSlotList>

◦ <slot start = "1400" end = "1450“ status=“open”/>

◦ <slot start = "1600" end = "1650“ status=“booked”/>

◦ </openSlotList>

12

GET /doctors/mjones/appointments/?date=20100104

HTTP/1.1 200 OK<openSlotList>

<slot start = "1400" end = "1450“ status=“open”>

<link rel=“slots/book” uri=“1400”/>

<slot/>

<slot start = "1600" end = "1650“ status=“booked”>

<link rel=“slots/move” uri=“1600”/>

<link rel=“slots/cancel” uri=“1600”/>

<slot/>

</openSlotList>

13

It’s very hard to be fully REST-style compatible.

Most of modern REST API implementations (Flickr api, Twitter api, Google calendar api) are just Level 1 and Level 2.

Specs based on REST:◦ WebDav protocol

◦ Odata protocol (designed for Entity Framework)

14

15

◦ /workflows/

◦ /workflows/<workflow Id>/ - bad

◦ /workflows/<workflow Id>-<workflow Name>/ - good

◦ /workflows/<workflow Name>/ - okay

16

Permanent. Should not be changed with time.

No special chars or file extensions (.php, .aspx) if they are not meaningful.

Context friendly.◦ /users/current/details

vs. /users/user-anton/details

◦ /forecasts/cambridge/today

may redirects to, say, /forecasts/cambridge/2009-04-26

17

URI should be human readable and easily guessed. Each part should be meaningful. All URI parts together should be

good nested, and help visualize the site structure.

◦ /cars/alfa-romeos/gt

Nouns, not verbs. Resource Names: prefer to use lower-case and hyphen instead of

spaces.

◦ /tasks/by-a-new-car

Resource IDs: prefer to use additional meaning prefix.

◦ /tasks/task-17◦ /conversations/conversation-{id}/todo-list-{id}/todo-{id}

18

/workflows/ ◦ GET – Get a list (?)

◦ POST - Create 201 (Created), Location:<new url>

/workflows/SomeItem◦ GET - Read

◦ PUT - Update

◦ DELETE - Delete

◦ PATCH – Partial update

19

You should introduce your own WEB-Methods.

Examples: /workflows/SomeItem

<OPERATION> - Non-standard operations

BOOK

BUY

CALCULATE

LOCK

RENT

… .etc

from WebDav: /workflows/SomeItem

MOVE Destination: <new url>

COPY Destination: <new url>

20

/workflows/SomeItem/<operation> POST - Non-standard operations

21

Less Db identifiers

More names and URLs

Human readable

No .Net/Java specifics: ◦ type: “MyNamespace.Workflow”

URL for hierarchies

WebDav - for file systems.◦

22

No complex inner structures :◦ “name”: “Object name”

◦ “userfields”: [

{

Id:17,

name: “Permissions”

type: “list of checkboxes”

Value: [

{“id”:24, “value” “Open allowed” }

{“id”:28, “value” “Close allowed” }

]

}

◦ ]

Keep all simple and human readable:◦ “name”: “Object name”

◦ “Permissions”: [“Open allowed”, “Close allowed”] (! manual serialization may be required)

23

24

Option #1: URL

/workflows/?name=My&date=2007

25

Option #2: Advanced URI

/workflows/?date=[MORE]2007 (?date=<2007)

?name=[LIKE]Jo

?name=[LIST]Jo,Mary,Anton,

?type.name=Lab1

?[order]=name,date

?[fields]=id,name

26

Odata◦ service.svc/Posts?$filter=OwnerUserId eq 209

◦ service.svc/Users?$filter=substringof('SQL',Title) or substringof('sql-server',Tags)&$format=json

Mongo◦ db/collections/?filter_type=cluster&filter_id=1&limit=-10

Gdata◦ /feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

restSQL◦ /restsql/res/Actor?first_name=JULIANNE&last_name=DENCH&_limit=10&_offset=0

27

Option #3: SQL◦ Separate functionality

◦ Require of supporting public schema & security!

◦/sql?q=SELECT * FROM workflows WHERE name=My AND type=system AND date < 2007&page=1&pagesize=20

28

SELECT * FROM workflows WHERE name=My AND type=system AND date < 2007

ParsingValidatingTransformingPaging

SELECT TOP 20 w.id, w.name, w.type, cfv.[Field1] FROM workflows wINNER JOIN permissions p

ON p.id = p.objectId AND p.userId= <userId>INNER JOIN customfieldvalue cfv

ON p.id = cfv.objectId AND cfv.name = “Field1”WHERE name=My AND type=system AND date < 2007

/sql?q=SELECT …

29

Send user-password with each request (like Basic authentication) ◦ REST-way style

◦ Not always practical

Session ID in header (implemented)◦ Authorization: RESTAPI realm=“<Session ID>”

Auth. Cookie (implemented)

Auth. Cookie of main Web UI (implemented)

30

By URL◦ api/ver1/*

By header

◦ X-Rest-Api-Version: 1

By mime-type◦ Accept: application/vnd.restapiv1+json;

◦ Accept: application/vnd.restapi+json; version=1;

31

Error Codes◦ 400 – Bad request (wrong json, ValidationException)◦ 401 – Unauthorized (no Session ID)◦ 404 – Not Found - ObjectDoesNotExistException◦ 409 – Conflict - ObjectAlreadyExistException◦ 500 – Unexpected, unknown error◦ 503 – Service Unavailable

SQL timeout Request limit

Retry-After: <seconds>

Error Meta:error:{

errorNumber: 500message: “”stacktrace: “<for dev only>”

}

32

33

SOAP

/Auth.asmx

/Workflows.asmx

/Tasks.asmx

REST

/sessions/

/processes/workflows/

/processes/tasks/

34

Well defined standard

Complex format

Meta Describer: WSDL

Not intended to be human readable

Excellent support in most IDEs (stub generation)

Hard to call from JavaScript

Each service – separate and independent item ◦ Auth.asmx

◦ Workflow.asmx

35

Not standardized - is a style

Conforms to REST style

Lead to design human readable API:◦ URL, names, serialized types

Bad support in most IDEs (problems with subs generation)

Easy to call from JavaScript

Popular

Each service are not separate – solid api:◦ /sessions/◦ /processes/workflows/◦ /processes/tasks/

36

REST – it’s not spec, it’s architectural style◦ It’s an art!

Leverage HTTP! URL, Headers, Mime, Accepts

Human readable URLs, XML and JSON !

37

38

http://xpinjection.com/2012/06/14/rest-in-uadevclub-july-5/ http://video.yandex.ua/users/xpinjection/view/192/ http://video.yandex.ua/users/xpinjection/view/193/ http://video.yandex.ua/users/xpinjection/view/194/

http://martinfowler.com/articles/richardsonMaturityModel.html http://www.iana.org/time-zones http://www.w3.org/TR/cors/ https://developers.google.com/gdata/docs/2.0/reference#Partia

lResponse http://www.mongodb.org/display/DOCS/Advanced+Queries http://restsql.org/doc/ref/index.html http://www.hanselman.com/blog/CreatingAnODataAPIForStackO

verflowIncludingXMLAndJSONIn30Minutes.aspx Libs:

◦ http://easyxdm.net/wp/◦ https://github.com/bigeasy/timezone

39