Building Adaptable APIs with NARWHL (API Days Paris)

Intel Confidential — Do Not Forward

Taming The RESTed NARWHLAn Approach to Building Adaptable APIs

2

3

Is this RESTful?

http://api.example.com/events/query.json?id=87465

Twitter: @rzazueta http://www.narwhl.com

4

What About This?

Find “Rob Zazueta” in the employee Database.

GET /countries

[

"/countries/usa/states",

"/countries/can/provinces",

...

]

GET /countries/usa/states

[

"/countries/usa/states/al",

"/countries/usa/states/ak",

...

]

GET /countries/usa/states/ca

[

"/countries/usa/states/ca/divisions",

"/countries/usa/states/ca/employees",

...

]

GET /countries/usa/states/ca/employees[

"/countries/usa/states/ca/employees/alan_akbar

",

"/countries/usa/states/ca/employees/bill_allen"

...

]


5

Google: “What is a REST API?”


6

Consistency Counts


7

8

Introducing the RESTed NARWHL

A design framework to build RESTful

APIs intended for consumption by

applications built by people


9

I Want To Hear From YOU!

The RESTed NARWHL

http://www.narwhl.com


10

1. It’s how I describe intuitive APIs

Noun

As

Resource

With

Hyper

Links Twitter: @rzazueta http://www.narwhl.com

11

2. Narwhals are an awesome mashup

+ =


12

3. Narwhals are real.


13

Obligatory RMM Slide

Source: http://martinfowler.com/articles/richardsonMaturityModel.html


14

Use Cases Uncover Resources

A customer wants to browse for products by category.

A customer wants to add a product to their shopping cart.

A store admin wants to list all customers who bought a given

product.


15


A customer wants to browse for products by category.

A customer wants to add a product to their shopping cart.

A store admin wants to list all customers who bought a

given product.


16


Customers

Products

Categories

Shopping Cart

Store Admin


17

Endpoint Design Matters

/{resource_name}/{resource_identifier}


18


/products/73924


19


/categories/39/products/73924


20


Link: <http://api.example.com/products/73924>; rel="canonical"


21

Content Negotiation

WWBD?


22

Content Negotiation

application/x-shockwave-flash


Content Negotiation


Content Negotiation


25

Content Negotiation – Better Communication;

Saner Versioning

Start using specific MIME types in your responses –

even custom ones.

NOContent-Type: application/json

YESContent-Type: application/json;vnd.example.products+v1

26

Content Negotiation – Shared Profiles


27

Content Negotiation – Custom Profiles


28

Which Hypermedia Format?


29

Dynamic Client Generation Through Response Profiles


30

SDKs Suck Because:

• They’re one more thing to maintain

• They often assume functionality outside the API

• They get bloated


31

SDKs Are Necessary Because:

• No one wants to spend time figuring out your API.


32

Dynamic Code Libraries Rock Because:

• They reflect only what’s defined in the API

• They grow and change as the API iterates

• They feel more native to the developer


33

NARWHL Maturity Model*

Level 0: Nouns as Resources With Hyperlinks

Level 1: NARWHL JSON Responses

Level 2: Content Negotiation

Level 3: Response Profiles & Definitions

Awesomeness of NARWHL

*With apologies and thanks to Martin Fowler and Leonard Richardson


34

Don’t Make Me Beg…

The RESTed NARWHL

http://www.narwhl.com


Intel Confidential — Do Not Forward

Thank You!Rob Zazueta

[email protected]

@rzazueta

http://www.NARWHL.com

35

Software

Building Adaptable APIs with NARWHL (API Days Paris)