Webcast: Pragmatic REST: The Next Generation

©2015 Apigee Corp. All Rights Reserved.


Intro

• Why care about this topic?

• Why care about what we think?


Topics

• What is a "REST API" – Data-oriented versus Service-oriented APIs – Hypermedia – JSON representations – Collections • Versioning


History

Service-oriented Data-oriented

RPC

CORBA

SOAP/WSDL

"REST API"

NLS

Xanadu

Databases

World-Wide Web REST

?? Object-orientation

"REST API"


Opposing Perspectives

Service-oriented

Data behind operations

Data-oriented

Operations behind data


Opposing Perspectives

Service-oriented

getPerson(personId)

updatePerson(personId, data)

deletePerson(personId)

Data-oriented

http://primary-‐key-‐value

http://example.org/person/12345


Why We Like Data-Oriented APIs

• The primary value is the data it exposes • Data-Oriented is Simpler – Learn the data vs learn the services + the data – Don’t design an API at all, just use REST


What Is Important?

Are you wasting time repetitively documenting the standard HTTP REST patterns?


What would be better?

9 ©2015 Apigee. All Rights Reserved.

PetTracker

Dog People

dogs n people n

1 1

owner 1 dogs n birthDate birthDate hairColor furColor

name name

REST/HTTP

+


Follow the REST/HTTP patterns exactly

• E.g. – POST means Create. Response status code is 201. URL of

new resource is in the 'Location' header – PUT means 'replace', not 'update'. PATCH means 'update' – GET response includes ETag and Content-Location headers – PUT and PATCH require an 'If-Match' header – …



Gaps in HTTP/REST for programmatic use

• How do you represent relationships – Single-valued •  What is a hyperlink?

– Multi-valued •  What is a Collection/Cursor?

• HTML provides some answers for the human-readable web –  <a ref = "http://example.org/people/98765432">Joe Carraclough</a>

• What is the equivalent for JSON?



Hypermedia — Just Do It •  Most data is conceptually linked

– So show the links in the data

•  Myths – Hypermedia APIs are controversial (practiced by extremists) – Hypermedia APIs are difficult – Hypermedia APIs are 100% self-describing – Hypermedia APIs are not compatible with languages like

Swagger (or other DLs)


Service-Oriented Data-Oriented http://example.org/people http://example.org/people/{personID} http://example.org/people/{personID}/dogs http://example.org/dogs http://example.org/dogs/{dogID} http://example.org/dogs/{dogID}/owner plus

{"id": "12345678", "type": "Dog" "name": "Lassie", "fur_color": "brown", "owner": "98765432"}

and {"id":"98765432", "type": "Person" "name": "Joe Carraclough", "hair_color": "brown"}

{"self": "http://example.org/", "type": "PetTracker", "dogs": "http://example.org/dogs", "people": "http://example.org/people}

and {"self": "http://example.org/dogs/12345678", "type": "Dog", "name": "Lassie", "fur_color": "brown", "owner": "http://example.org/people/98765432"}

and {"self": "http://example.org/people/98765432", "type": "Person", "name": "Joe Carraclough", "hair_color": "brown", "dogs": "http://example.org/people/98765432/dogs"}


Cursor/Collection { "self": "http://example.org/dogs", "type": "Collection", "items": [

{"self": "http://example.org/dogs/12345678", "type": "Dog", "name": "Lassie", "fur_color": "brown", "owner": "http://example.org/people/98765432"}, {"self": "http://example.org/dogs/12345679", "type": "Dog", "name": "Lassie", "fur_color": "brown", "owner": "http://example.org/people/98765432"} ]

}



Cursor/Collection { "self": "http://example.org/dogs?limit=10", "type": "Page", "collection": "http://example.org/dogs", "next": "http://example.org/ZG9ncz87bGFzdD0xMA==", "previous": "http://example.org/ZG9ncz87Zmlyc3Q9MTA=", "items": [

{"self": "http://example.org/dogs/12345678", "type": "Dog", "name": "Lassie", "fur_color": "brown", "owner": "http://example.org/people/98765432"}, {"self": "http://example.org/dogs/12345679", "type": "Dog", "name": "Lassie", "fur_color": "brown", "owner": "http://example.org/people/98765432"} ]

}



A File in Google Drive {

"kind": "drive#file",

"id": "1cjKSwWlryNfRs-‐durx_8n0dGTUWE_klBrP8IuEYTUu0",

"etag": "9vYBbk7LzzrwpsohQSOkWalvY6Y/MTQ0Mjc1ODk5NzAwMQ",

"selfLink": "https://www.googleapis.com/drive/v2/files/1cjKSwWlryNfRs-‐durx_8n0dGTUWE_klBrP8IuEYTUu0",

"alternateLink": "https://docs.google.com/a/apigee.com/document/d/1cjKSwWlryNfRs-‐durx_8n0dGTUWE_klBrP8IuEYTUu0/edit?usp=drivesdk",

"embedLink": "https://docs.google.com/a/apigee.com/document/d/1cjKSwWlryNfRs-‐durx_8n0dGTUWE_klBrP8IuEYTUu0/preview",

...

"title": "Web API Design edition 2",

"mimeType": "application/vnd.google-‐apps.document",

...

"createdDate": "2015-‐07-‐10T15:26:34.567Z",

"modifiedDate": "2015-‐09-‐20T14:23:17.001Z",

"modifiedByMeDate": "2015-‐09-‐20T14:23:17.001Z",

"lastViewedByMeDate": "2015-‐09-‐30T23:16:08.011Z",

"markedViewedByMeDate": "1970-‐01-‐01T00:00:00.000Z",

"version": "41819",

...


A Folder's Children in Google Drive {

"kind": "drive#childList",

"etag": "9vYBbk7LzzrwpsohQSOkWalvY6Y/73yTWsreOINR667_OZQCurHB09o",

"selfLink": "https://www.googleapis.com/drive/v2/files/0B2Pq-‐qMI4R2jYVdudkdNMld3Vm8/children",

"items": [

{

"kind": "drive#childReference",

"id": "1BuYLy9FkXpILYmwnRNetnUFCC9D-‐U35PrJcO_9YsuW0",

"selfLink": "

https://www.googleapis.com/drive/v2/files/0B2Pq-‐qMI4R2jYVdudkdNMld3Vm8/children/1BuYLy9FkXpILYmwnRNetnUFCC9D-‐U35PrJcO_9YsuW0",

"childLink": "https://www.googleapis.com/drive/v2/files/1BuYLy9FkXpILYmwnRNetnUFCC9D-‐U35PrJcO_9YsuW0"

},

{

"kind": "drive#childReference",

"id": "1pfcXbfX9PaUk12Cywqav9H77-‐DQEWhxjeKHgu1qpAi8",

"selfLink": "

https://www.googleapis.com/drive/v2/files/0B2Pq-‐qMI4R2jYVdudkdNMld3Vm8/children/1pfcXbfX9PaUk12Cywqav9H77-‐DQEWhxjeKHgu1qpAi8",

"childLink": "https://www.googleapis.com/drive/v2/files/1pfcXbfX9PaUk12Cywqav9H77-‐DQEWhxjeKHgu1qpAi8"

}

]

}


Principles Illustrated

• Use JSON • Keep your JSON simple and flat •  Links can be simple properties • Collections are resources too • Provide a "self" property • Provide a "kind" property


Perma-links Versus ‘Query URLs’

'Query URLs': http://example.org/?type=Person&id=personID http://example.org/people/{personId} http://example.org/people/{personName}

vs Perma-links http://example.org/cGVyc29uczt7cGVyc29uX2lkfS9kb2dz


API Versioning


The Most Complex Form of Versioning •  Multiple versions of the same resource are available simultaneously •  Client selects the version it needs •  Cons: –  It is expensive to implement –  It doesn’t always work anyway

•  Pros: –  Supports frequent versioning

•  Very few people actually do this


Why Doesn’t It Always Work?

•  It doesn't work if you make substantial data-model changes – You won’t be able to update through the old versions

•  It doesn't work for micro-services – Consider: •  /v1/orders/123456 •  /v2/accounts/9876765

– Now consider: •  /v2/recent_changes

– Should it include v1 format of orders, "or v2 format of orders?


Pragmatic Versioning

• Only one version of each resource available at any one time –  Make sure clients can tolerate minor changes

•  Version upgrade is infrequent – Major breaking change

•  Less elegant version: – https://api.acmecorp.com/orders/v1/123456 – https://api.acmecorp.com/orders/v2/123456

•  Elegant version – the ‘no-versioning’ strategy for versioning – https://api.acmecorp.com/orders/123456 – https://api2.acmecorp.com/orders/123456


Summary

•  Data-oriented APIs •  Simple, flat JSON •  Hypermedia –  Hypermedia links can be simple JSON properties

•  Simple collections that are also resources •  Simple, ‘no versioning’ versioning strategy

Thank you

Martin Nally @mpnally

Marsh Gardiner @earth2marsh

Date post:	21-Jan-2018
Category:	Technology
Upload:	apigee-google-cloud
View:	10,619 times
Download:	0 times

Webcast: Pragmatic REST: The Next Generation

Technology