Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Lone Star PHP 2017 - Your API is Bad and You Should Feel Bad

Lone Star PHP 2017 - Your API is Bad and You Should Feel Bad

Do you hate the Facebook API? We all do as well. So stop writing your API in their footsteps.

In this talk we will walk through how to construct a RESTful API, what makes an API your users/developers will love, and why you should eat your own dog food with API Driven Development.

Ben Edmunds

April 21, 2017
Tweet

More Decks by Ben Edmunds

Other Decks in Technology

Transcript

  1. Title Title Ben Edmunds Open Source Author PHP Town Hall

    Podcast CTO at Mindfulware Who is this guy?
  2. Title Title RESTful API Basics API Design Implementing your API

    Versioning, Auth, & Rate Limiting What Will We Cover?
  3. Title Title What Will We Cover? REST Representing Data Stable

    Interface State-less Gives Server More Control
  4. Title Title What Will We Cover? GraphQL Querying Data Changing

    Interface State-less Gives Client More Control
  5. Title Title Representational State Transfer HTTP Methods GET, POST, PUT,

    PATCH, DELETE Expressive Real-World Usage What is REST?
  6. Title Title Most widely used data format is JSON Javascript

    Object Notation { key: ‘value’, anotherKey: ‘value2’ } What is REST?
  7. Title Title JSON usage in Javascript = familiar var object

    = { key: ‘value’, anotherKey: ‘value2’ }; What is REST?
  8. Title Title Outputs {key: ‘value’} PHP echo json_encode(array( ‘key’ =>

    ‘value’ )); JSON encoding is supported natively in most languages What is REST?
  9. Title Title Outputs array( ‘key’ => ‘value’ ) $json_data =

    “{key: ‘value’}”; print_r(json_decode($json_data)); JSON decoding is just as simple PHP What is REST?
  10. Title Title Different Opinions PUT = create (idempotent) POST =

    create (unknown resource) PUT/PATCH = update (resource is known) Put vs Post API Design
  11. Title Title PUT = UPDATE api.domain.com/user/2 { id: 2, first_name:

    ‘bob’, last_name: ‘cat’ } API Design
  12. Title Title PATCH = IDEMPOTENT Needs all identifying info Basically,

    include the ID Does not need all info Series of changes API Design
  13. Title Title A single Object maps to a singular URL

    api.domain.com/user/2 api.domain.com/company/3 API Design
  14. Title Title Common actions across most objects GET /user/2 GET

    /company/3 DELETE /user/2 DELETE /company/3 API Design
  15. Title Title https://site.com/api/statuses Maps to all of the statuses “Statuses”

    could be: SQL table NoSQL collection Aggregate Data API Design
  16. Title Title Creating If you know all of the data

    (including the ID) PUT https://site.com/api/status/1234 API Design
  17. Title Title Creating If you know all of the data

    (including the ID) PUT https://site.com/api/status/1234 No matter how many times you send this data only one resource should ever be created Idempotent API Design
  18. Title Title Creating If you know all of the data

    (including the ID) PUT https://site.com/api/status/1234 { id: 1234, retweeted: false, active: true } API Design
  19. Title Title Creating If you don’t know all of the

    data POST https://site.com/api/status Implementation
  20. Title Title Creating Each time you post this data a

    new resource should be created Unique If you don’t know all of the data POST https://site.com/api/status Implementation
  21. Title Title Creating If you don’t know all of the

    data POST https://site.com/api/status {user_id: 1, text: ‘Test Status’ } Implementation
  22. Title Title Creating If you don’t know all of the

    data POST https://site.com/api/status {user_id: 1, text: ‘Test Status’ } Response {succes: true, id: 123 } Implementation
  23. Title Title Reading Get all of the statuses that have

    been retweeted and are active GET https://site.com/api/statuses ? retweeted=1&active=1 API Design
  24. Title Title Updating We know all the data PUT https://site.com/api/status/123

    {id: 123, user_id: 1, text: ‘Test Status 2’ } Implementation
  25. Title Title Updating We know some of the data PATCH

    https://site.com/api/status/123 {id: 123, text: ‘Test Status 3’ } Implementation
  26. Title Title Delete Just pass the identifying information {id: 123}

    DELETE https://site.com/api/status/123 API Design
  27. Title Title Relationships Get the user that posted a status

    GET https://site.com/api/status/1234/user API Design
  28. Title Title Route newest API through https://api.site.com GET https://site.com/api/v2/statuses GET

    https://site.com/api/statuses = Versioning How to handle versioning?
  29. Title Title Hypermedia Controls Links to Related Content HATEOAS {

    success: true, id: 123, links: { “rel”: ‘self’ “url”: ‘/status/123’ }, { “rel”: ‘user’ “url”: ‘/status/123/user’ } }
  30. Title Title Hypermedia Controls Links to Related Content HATEOAS {

    success: false, error: { “code”:‘errorFail’ “message”: ‘You have Failed!’ “url”: ‘http://domain.com/docs/errorFail’ } }
  31. Title Title Consumer = Internal Client Server Request -> w/AccessToken

    Access Token = Service Key+Client Key Authentication
  32. Title Title https://leanpub.com/build-apis-you-wont-hate Book - Build APIs You Won’t Hate

    Tutorial - Demystifying REST https://tutsplus.com/tutorial/demystifying-rest/ Resources
  33. Title Title http://aaronparecki.com/articles/ 2012/07/29/1/oauth2-simplified Blog - OAuth 2 Simplified Book

    - OAuthello https://leanpub.com/oauthello-a-book-about- oauth/ Resources
  34. Q/A