FUTUREPROOFREST APIS
Mark StaffordMicrosoft
Fast forward
• Three decades
• A few degrees
• A wife
• Four! kids
LESS DREAMING,
MORE THINKING
HTTP APIS
Standards are good
API franca • HTTP APIs can learn from lingua francas
• HTTP APIs should be interoperable
• Not making enough of an effort
• Most HTTP APIs are “bespoke” – built-to-fit
• There are no bonus points for originality
THIS TALK IS ABOUT FUTUREPROOFING
Disclaimers
• These are my opinions
• The opinions are conversation starters
• Focus on the future, not the past
• Not exhaustive
• Feedback appreciated
1.Policies2. Versioning
3. Headers
4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
Important policies
• Terms of service
• Privacy
• Deprecation
• Breaking change
• SLAs
• Rate limits
• Licenses
• Support
Before & after
• Nobody is doing this right
• Twitter gets honorable mention
What should it look like?
• All policies in one place
• Somewhere developers will “stumble” over them
• Refresh developers on policies
• Consider versioning the API for policy changes
1. Policies
2.Versioning3. Headers
4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
3 ways • Path, e.g., http://api/v1/
• Headers, e.g., x-version: 1.0
• Query string, e.g., http://api?version=1.0
PATH
Versioning principles
• Version from the beginning
• Version both public and private APIs
Additional consideration
s
• How long to keep a version around
• How to deprecate a version
• Whether to require clients to request version
• How to handle breaking changes if version is not required
• Provide a –pre (or similar) suffix
Before & after
1. Policies
2. Versioning
3.Headers4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
HEADERS ARE ONLY FOR DATA CONCEPTUALLY
SCOPED TO THE REQUEST OR RESPONSE
Rule of thumb
Pagination example
WHAT HAPPENS WHEN YOU WANT TO RETURN
MULTIPLE COLLECTIONS?
Options • Cram links header with many links
• Force SELECT (N+1) requests
Etag example
Collection Questions
• Can you guarantee an etag for the collection?
• Where do etags for the embedded resources go?
CONSIDER HEADER USAGE ON CASE-BY-
CASE BASIS
Before & after
1. Policies
2. Versioning
3. Headers
4.Pagination5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
2 TYPES
Client-driven
pagination
• Client-driven: skip, take, top, etc
• Client-initiation keeps this from being a breaking change
Server-driven paging
• Data has a tendency to grow
• Server should force pagination to prevent DoS
• Clients should always be prepared for paginated collections
Server-driven paging
guidance
• Tell clients to expect that any collection may be paginated
• Decide what a continuation token is (opaque string? URL?)
• Put continuation tokens in response body
Server-driven paging
examples
HAL
Siren
Server-driven paging
examples
OData
Before & after
1. Policies
2. Versioning
3. Headers
4. Pagination
5.Separate data & metadata6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
Ambiguity is bad
• Forcing consumers to the docs is bad
• Ambiguity limits extensibility
Metadata examples
HAL
Siren
Metadata examples
JSON-LD
OData
OData annotation
s
Target parent
Target sibling
Before & after
1. Policies
2. Versioning
3. Headers
4. Pagination
5. Separate data & metadata
6.Don’t mint mime types7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
TO MINT OR NOT TO MINT?
NEW MIME TYPES OFTEN LEAD TO
BREAKING CHANGES
Introducing new
resource types
• HAL: doesn’t care about type
• Siren: doesn’t care about type
• OData: describes type when necessary
• JSON-LD: always describes type
Best of both
worlds
• Unambiguous typing
• No media type minting
Before & after
• Still looking for a real-world example of minting
1. Policies
2. Versioning
3. Headers
4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7.Wrap arrays & primitives8. Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
JSON ALLOWS ROOT-LEVEL
ARRAYS, BUT…
WHERE DOES METADATA GO?
Array metadata
• Pagination links
• Count
• Self-link
• Type information
Also wrap primitives
Before & after
1. Policies
2. Versioning
3. Headers
4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8.Responses should be self-describing
9. Use a consistent query syntax
10. Be consistent elsewhere
Self-description is a REST
constraint
CLIENT ONLY NEEDS THE RESPONSE TO
INTERPRET THE RESPONSE
Means of self-
describing
JSON-LD
OData
Github Webhooks
Scenarios • Webhooks
• Push notifications
• Asynchronous clients
• Intermediary processing
Before & after
1. Policies
2. Versioning
3. Headers
4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9.Use a consistent query syntax10. Be consistent elsewhere
Appcelerator
VERY LITTLE CONSISTENCY
ACROSS REST APIS
WORSE, VERY LITTLE CONSISTENCY WITHIN
REST APIS
Query needs
• Consistent
• Robust
• NOT original
Two major options
Lucene
OData
NO BONUS POINTS FOR ORIGINALITY
1. Policies
2. Versioning
3. Headers
4. Pagination
5. Separate data & metadata
6. Don’t mint mime types
7. Wrap arrays & primitives
8. Responses should be self-describing
9. Use a consistent query syntax
10.Be consistent elsewhere
CONSISTENCY DOESN’T JUST APPLY
TO QUERY SYNTAX
Areas of consistenc
y
• Resource paths
• Serialization
• Deterministic responses
• Error codes
First look: Model-first HTTP APIs
• Use Swagger API description format
• Use Swagger tooling
• Introduce new YAML syntax
• Resource model only
DEMO
3 takeaways
• Does not require HTTP expertise
• Builds consistent HTTP APIs
• Your input necessary
ODATA: WORST BRAND NAME
EVER!
OData • OData can help any HTTP API
• Public standard (OASIS, ISO)
Who?
Enjoy the REST of
the conference
(har, har)
Contact info
• Mark Stafford
• Microsoft
• http://www.odata.org