futureproofing rest apis

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

Twitter

Facebook

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

• mastaffo@microsoft.com

• http://www.odata.org