Get Some REST: Best RESTful API Practices About Me Lorna Jane - - PowerPoint PPT Presentation

Get Some REST: Best RESTful API Practices

About Me

2

• Lorna Jane Mitchell
• PHP Consultant/Developer
• API Specialist
• Author of PHP Master
• Twitter: @lornajane
• Website: http://lornajane.net

About REST

3

• REpresentational State Transfer
• Everything is a resource
• Representations get passed around
• Great for data-driven applications

Not RESTful

4

Clues that your service isn’t RESTful:

• It has a single endpoint

Not RESTful

4

Clues that your service isn’t RESTful:

• It has a single endpoint
• All requests are POSTs

Not RESTful

4

Clues that your service isn’t RESTful:

• It has a single endpoint
• All requests are POSTs
• Response metadata is in the body, not header

Not RESTful

4

Clues that your service isn’t RESTful:

• It has a single endpoint
• All requests are POSTs
• Response metadata is in the body, not header
• There are verbs in the URL

Not RESTful

4

Clues that your service isn’t RESTful:

• It has a single endpoint
• All requests are POSTs
• Response metadata is in the body, not header
• There are verbs in the URL
• The URL includes method names

RESTful != Useful

Best Practices

Use Existing Skills/Tools

Existing Skills

8

MVC Applications

9

Model-View-Controller becomes Model-Controller-Output Handler

MVC Applications

10

Model-View-Controller becomes Model-Controller-Output Handler

• utput

controller model index

Output Handlers: JSON

11

class JsonView extends ApiView { public function render($content) { header('Content-Type: application/json; charset=utf8'); echo $this->buildOutput($content); return true; } /** * Function to build output, can be used by JSON and JSONP */ protected function buildOutput ($content) { $content = $this->addCount($content); $retval = json_encode($content, JSON_NUMERIC_CHECK); return $retval; } }

Meaningful URL Structure

Meaningful URLs

13

What would you expect to find at:

http://api.joind.in/v2.1/events?filter=upcoming

Meaningful URLs

13

What would you expect to find at:

http://api.joind.in/v2.1/events?filter=upcoming http://api.joind.in/v2.1/events/853

Meaningful URLs

13

What would you expect to find at:

http://api.joind.in/v2.1/events?filter=upcoming http://api.joind.in/v2.1/events/853 http://api.joind.in/v2.1/events/853/talks

Meaningful URLs

13

What would you expect to find at:

http://api.joind.in/v2.1/events?filter=upcoming http://api.joind.in/v2.1/events/853 http://api.joind.in/v2.1/events/853/talks http://api.joind.in/v2.1/talks/6232

Meaningful URLs

13

What would you expect to find at:

http://api.joind.in/v2.1/events?filter=upcoming http://api.joind.in/v2.1/events/853 http://api.joind.in/v2.1/events/853/talks http://api.joind.in/v2.1/talks/6232 http://api.joind.in/v2.1/talks/6232/comments

Verbs and URLs

14

These URLs give us representations of either resources or collections

• f resources

We use HTTP verbs to operate on these resources

Verb Collection Resource GET fetch resources fetch resource POST create a resource in this collection PUT create or update a resource here PATCH update part of a resource DELETE delete a resource

Identifying Resources

15

What is a "resource"?

• Maybe a database row
• Maybe an item with some information from other tables
• Talks also show speaker names, for example
• Maybe a sub-resource

Considering Sub-Resources

16

Common pitfall: http://example.com/articles/42/activate

Considering Sub-Resources

16

Common pitfall: http://example.com/articles/42/activate We have two options GET http://example.com/articles/42, change the "active" flag, and PUT it back

Considering Sub-Resources

16

Common pitfall: http://example.com/articles/42/activate We have two options GET http://example.com/articles/42, change the "active" flag, and PUT it back Make a subresource, then you can just work with

http://example.com/articles/42/active

Hypermedia

Hypermedia

18

GET http://api.joind.in/v2.1/events/853

Hypermedia

19

• Consumers can follow links rather than construct them
• Providers can change link structures

$event_url = 'http://api.joind.in/v2.1/events/853'; $event_data = json_decode( file_get_contents($event_url), TRUE); // get event talks $talks = json_decode( file_get_contents($event_data['events'][0]['talks_uri']), TRUE ); print_r($talks['talks'][0]);

Content Negotiation

Content Negotiation

21

We use the Accept and Content-Type headers to agree what formats to use. Common examples:

• application/json
• application/xml
• text/html

Next stage: use Media Types for custom/versioned representations

Content Negotiation Confession

22

The joind.in API also allows ?format=json as an override

Error Handling

Simple Error Rules for Service Providers

24

• Use expected format
• Give meaningful messages
• Be consistent

Exceptions Help Consistency

25

• utput

controller model index

Exceptions Help Consistency

26

function handle_exception($e) { // pull the correct format before we bail global $request; header("Status: " . $e->getCode(), false, $e->getCode()); $request->view->render(array($e->getMessage())); } set_exception_handler('handle_exception');

When Things Go Wrong

Crisis Strategies

28

• Lots of logging!
• Logging rather than debug output if the client expects JSON
• Proxy or network analyser
• Inspects traffic without application changes
• e.g. Wireshark or Charles proxy
• Drop back to last known good outcome
• Increase complexity in "baby steps"

Protecting Yourself

Isolate External Dependencies

30

Never call an API from your own code - have a class that wraps it. You can:

• cache results if it is slow/flaky
• replace it in one place later, if needed
• write tests to check the API is still doing what you expect
• write a mock object to replace it with for your own tests

Respect the Danger

31

Website Digital Identity API Product API Database Mobile Application logic layer

Respect the Danger

32

abyss Website Digital Identity API Product API Database Mobile Application logic layer

Deliver on Time

33

How to estimate for API integration?

• You can’t estimate an unknown task
• Invest time in a prototype
• In agile speak, a "spike"

Best Practice for RESTful Applications

34

• Use existing tools, skills and conventions
• Deliver what’s useful to your users
• Plan defensively

Questions?

Thanks!

36

@lornajane

http://lornajane.net