Reprising an extremely popular session from our I Love APIs 2015 conference, Apigee’s Marsh Gardiner and Martin Nally will review recent trends in API design, including topics such as hypermedia and how Swagger's opinions on API design influence common patterns. Because this is a pragmatic approach, this session will be built on real-world examples.

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