Webcast: Pragmatic REST: The Next Generation
11 likes15,890 views
The document discusses the design and implementation of REST APIs, emphasizing a data-oriented approach over service-oriented designs. It highlights the importance of simple JSON representations, hypermedia links, and effective API versioning strategies. Key principles include maintaining clarity in data exposure and using flat structures for resource representation.
![©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.](https://image.slidesharecdn.com/webcast-pragmatic-rest-next-generation-151217175156/85/Webcast-Pragmatic-REST-The-Next-Generation-14-320.jpg)
![©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.](https://image.slidesharecdn.com/webcast-pragmatic-rest-next-generation-151217175156/85/Webcast-Pragmatic-REST-The-Next-Generation-15-320.jpg)
![©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"
}
]
}](https://image.slidesharecdn.com/webcast-pragmatic-rest-next-generation-151217175156/85/Webcast-Pragmatic-REST-The-Next-Generation-17-320.jpg)
Webcast: Pragmatic REST: The Next Generation
- 1. ©2015 Apigee Corp. All Rights Reserved.
- 2. ©2015 Apigee Corp. All Rights Reserved. Intro • Why care about this topic? • Why care about what we think?
- 3. ©2015 Apigee Corp. All Rights Reserved. Topics • What is a "REST API" – Data-oriented versus Service-oriented APIs – Hypermedia – JSON representations – Collections • Versioning
- 4. ©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"
- 5. ©2015 Apigee Corp. All Rights Reserved. Opposing Perspectives Service-oriented Data behind operations Data-oriented Operations behind data
- 6. ©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
- 7. ©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
- 8. ©2015 Apigee Corp. All Rights Reserved. What Is Important? Are you wasting time repetitively documenting the standard HTTP REST patterns?
- 9. ©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 +
- 10. ©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.
- 11. ©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.
- 12. ©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)
- 13. ©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"}
- 14. ©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.
- 15. ©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.
- 16. ©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", ...
- 17. ©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" } ] }
- 18. ©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
- 19. ©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
- 20. ©2015 Apigee Corp. All Rights Reserved. API Versioning
- 21. ©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
- 22. ©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?
- 23. ©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
- 24. ©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
- 25. Thank you Martin Nally @mpnally Marsh Gardiner @earth2marsh