Crafting REST APIs Mobile Devs Will Love

This talk will cover best practices for creating REST APIs that don't make mobile developers want to cry.

We'll start with an overview of what it means to create a RESTful API, and then go through some best practices on encryption and versioning. We'll then show how your documentation can be used to validate input and test the responses your API gives, meaning the documentation becomes the source of truth for the API. No more outdated documentation and frustrated developers!

Matt is a developer at ribot who has worked on Android, iOS and API servers.

Transcript

1. Crafting REST APIs REST APIs Mobile Developers Will Love Matt Oakes
2. Talk Overview
3. About Me
4. What is REST?
5. Resources
7. Requests
8. HTTP Verbs • GET • Gets resource • POST • Create a new resource • PUT • Update a resource • PATCH • Update part of a resource • DELETE • Deletes a resource
9. Resource URIs • GET /games • Retrieves a collection of games • GET /games/11 • Retrieves a specific game • POST /games • Creates a new game • DELETE /games/11 • Deletes game #11 • PUT /games/11 • Updates game #11 • PATCH /games/11 • Partially updates game #11
10. Sub-resources • GET /games/11/rounds • Retrieves collection of rounds for game #11 • GET /games/11/rounds/4 • Retrieves round #4 for game #11 • POST /games/11/rounds • Creates a new round in game #11
12. Responses
13. HTTP Status Codes • 200 OK • Response was successful • 201 Created • Response to a POST that results in a creation • 204 No Content • Response to a successful request that won't be returning a body (like a DELETE request) • 400 Bad Request • The request is malformed, such as if the body does not parse or there are validation errors • 404 Not Found • When a non-existent resource is requested • 401 Unauthorized • When no or invalid authentication details are provided • 403 Forbidden • When authentication succeeded but authenticated user doesn't have access to the resource
14. Response Body • JSON • Human and machine readable • Widely supported
15. Best Practices
16. Best Practices • TLS/SSL everywhere • Documentation • Testing
17. TLS/SSL Everywhere
18. iOS 9 Requires TLS for all connections http://j.mp/apptransportsecurity
19. HTTPS Is Not Enough Secure certificate & correct server settings Test at: http://j.mp/ssllabtest Documentation at: http://j.mp/ssllabsdocs
22. Documentation
23. List All Resource URIs Yes… Really…
24. Request & Response Format • Exactly what you expect in • What property name? • Which properties are required? • What types are they? • Exactly what you’ll send back • What are the property names? • Which ones may not be sent back (and why)? • What types are they?
25. Document Errors
26. API Blueprint A language and set of tools to describe your API https://apiblueprint.org/
27. ribot API Example
31. JSON Schemas A language to describe the structure and content types of JSON http://json-schema.org/
34. Request Validation Middleware
38. Testing
39. Test Using the Documentation The documentation is the source of truth
45. Test-Driven Development
46. Summary
47. Thank You! Any Questions? @matto1990