Download - Webcast: Pragmatic REST: The Next Generation
©2015 Apigee Corp. All Rights Reserved.
Intro
• Why care about this topic?
• Why care about what we think?
©2015 Apigee Corp. All Rights Reserved.
Topics
• What is a "REST API" – Data-oriented versus Service-oriented APIs – Hypermedia – JSON representations – Collections • Versioning
©2015 Apigee Corp. All Rights Reserved.
History
Service-oriented Data-oriented
RPC
CORBA
SOAP/WSDL
"REST API"
NLS
Xanadu
Databases
World-Wide Web REST
?? Object-orientation
"REST API"
©2015 Apigee Corp. All Rights Reserved.
Opposing Perspectives
Service-oriented
Data behind operations
Data-oriented
Operations behind data
©2015 Apigee Corp. All Rights Reserved.
Opposing Perspectives
Service-oriented
getPerson(personId)
updatePerson(personId, data)
deletePerson(personId)
Data-oriented
http://primary-‐key-‐value
http://example.org/person/12345
©2015 Apigee Corp. All Rights Reserved.
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
©2015 Apigee Corp. All Rights Reserved.
What Is Important?
Are you wasting time repetitively documenting the standard HTTP REST patterns?
©2015 Apigee Corp. All Rights Reserved.
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
+
©2015 Apigee Corp. All Rights Reserved.
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 – …
10 ©2015 Apigee. All Rights Reserved.
©2015 Apigee Corp. All Rights Reserved.
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?
11 ©2015 Apigee. All Rights Reserved.
©2015 Apigee Corp. All Rights Reserved.
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)
©2015 Apigee Corp. All Rights Reserved.
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"}
©2015 Apigee Corp. All Rights Reserved.
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"} ]
}
14 ©2015 Apigee. All Rights Reserved.
©2015 Apigee Corp. All Rights Reserved.
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"} ]
}
15 ©2015 Apigee. All Rights Reserved.
©2015 Apigee Corp. All Rights Reserved.
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",
...
©2015 Apigee Corp. All Rights Reserved.
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"
}
]
}
©2015 Apigee Corp. All Rights Reserved.
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
©2015 Apigee Corp. All Rights Reserved.
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
©2015 Apigee Corp. All Rights Reserved.
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
©2015 Apigee Corp. All Rights Reserved.
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?
©2015 Apigee Corp. All Rights Reserved.
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
©2015 Apigee Corp. All Rights Reserved.
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