Save 37% off PRO during our Black Friday Sale! »

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.

22f21d5c22b930fd35dd98f25dedf6a4?s=128

Ben Edmunds

April 21, 2017
Tweet

Transcript

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

    Podcast CTO at Mindfulware Who is this guy?
  3. Title Title Ben Edmunds @benedmunds http://benedmunds.com Who is this guy?

  4. Title Title RESTful API Basics API Design Implementing your API

    Versioning, Auth, & Rate Limiting What Will We Cover?
  5. Title Title What about GraphQL / RPC / etc? What

    Will We Cover?
  6. Title Title What Will We Cover? REST Representing Data Stable

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

    Interface State-less Gives Client More Control
  8. Title Title What Will We Cover? RPC Executing Processes Can

    have State
  9. Title Title What Will We Cover? REST / GraphQL /

    RPC Gotta Catch Em All!
  10. Title Title Simple Similar to Sinatra FastRoute Testable Slim PHP

  11. Title Title RESTful API Basics

  12. Title Title Representational State Transfer HTTP Methods GET, POST, PUT,

    PATCH, DELETE Expressive Real-World Usage What is REST?
  13. Title Title Formats JSON* XML Anything What is REST?

  14. Title Title Most widely used data format is JSON Javascript

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

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

    ‘value’ )); JSON encoding is supported natively in most languages What is REST?
  17. 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?
  18. Warning This will be Opinionated

  19. Title Title Simple Expressive Intuitive API Design

  20. Title Title Simple Expressive Intuitive STABLE API Design

  21. Title Title Simple Expressive Intuitive STABLE CONSISTENT API Design

  22. Title Title Use the Facebook API DO THE OPPOSITE API

    Design
  23. Title Title Document! Document! Document! API Design

  24. Title Title To ADD or not to ADD API Driven

    Development API Design
  25. Title Title HTTP Status Codes HTTP Status Cats to the

    Rescue! API Design
  26. Title Title Status 2xx = Success API Design

  27. Title Title Status 3xx = Redirect API Design

  28. Title Title Status 4xx = Client Errors API Design

  29. Title Title Status 5xx = Service Errors API Design

  30. Title Title VERBS API Design

  31. Title Title POST/PUT GET PUT/PATCH DELETE HTTP Methods Create Read

    Update Delete = API Design
  32. Title Title POST/PUT = Create api.domain.com/user PUT if all values

    are known API Design
  33. Title Title GET = READ api.domain.com/user/2 API Design

  34. Title Title PUT = IDEMPOTENT Needs all info Basically, include

    the ID API Design
  35. Title Title Different Opinions PUT = create (idempotent) POST =

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

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

    include the ID Does not need all info Series of changes API Design
  38. Title Title PATCH = UPDATE api.domain.com/user/2 [{ id: 2, first_name:

    ‘bob’ }] API Design
  39. Title Title PATCH = UPDATE api.domain.com/user/2 [ {id: 2,first_name: ‘bob’}

    {id: 2,first_name: ‘bobby’} ] API Design
  40. Title Title DELETE = DELETE api.domain.com/user/2 API Design

  41. Title Title CONSISTENCY API Design

  42. Title Title URL endpoints represent data /user = user /company

    = company API Design
  43. Title Title A single Object maps to a singular URL

    api.domain.com/user/2 api.domain.com/company/3 API Design
  44. Title Title Objects map to plural URLs api.domain.com/users api.domain.com/companies API

    Design
  45. Title Title Common actions across most objects GET /user/2 GET

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

    could be: SQL table NoSQL collection Aggregate Data API Design
  48. Title Title https://site.com/api/status/1234 Maps to a single status with the

    ID of 1234 API Design
  49. Title Title Creating If you know all of the data

    (including the ID) PUT https://site.com/api/status/1234 API Design
  50. 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
  51. 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
  52. Title Title Creating If you don’t know all of the

    data POST https://site.com/api/status Implementation
  53. 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
  54. 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
  55. 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
  56. Title Title Reading Get all statuses GET https://site.com/api/statuses API Design

  57. Title Title Reading Complex requests that require additional data GET

    https://site.com/api/statuses API Design
  58. 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
  59. Title Title Updating We know all of the identifying information

    so we PUT updates API Design
  60. 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
  61. Title Title Updating We know some of the data PATCH

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

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

    GET https://site.com/api/status/1234/user API Design
  64. None
  65. Title Title How to handle versioning? GET https://site.com/api/v1/statuses GET https://site.com/api/v2/statuses

    Each version has a separate route - Versioning
  66. 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?
  67. Title Title Accept Headers (HATEOAS) Versioning Accept: application vnd.github.user.v4+json How

    to handle versioning?
  68. Title Title Hypermedia as the Engine of Application State HATEOAS

  69. -OAS

  70. Title Title Content Negotiation HATEOAS Hypermedia Controls

  71. Title Title Content Negotiation Accept: application/x-yaml Accept: application/json Request “Accept”

    Header (JSON,XML,YAML, etc) HATEOAS
  72. Title Title Content Negotiation Allow: GET, PUT, POST OPTIONS Http

    Request HATEOAS
  73. 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’ } }
  74. Title Title Hypermedia Controls Links to Related Content HATEOAS {

    success: false, error: { “code”:‘errorFail’ “message”: ‘You have Failed!’ “url”: ‘http://domain.com/docs/errorFail’ } }
  75. None
  76. Title Title Who’s the Consumer? User Service Internal Service Authentication

  77. Title Title Consumer = User OAuth Client Server Request Token

    -> <- Access Token Authentication
  78. Title Title Consumer = User Standard Many Diff “Flows” Complicated

    Spec OAuth 2 Authentication
  79. Title Title Consumer = User Client Server Request -> w/AccessToken

    OAuth 2 Authentication
  80. Title Title Consumer = Internal Client Server Request -> w/AccessToken

    Access Token = Service Key+Client Key Authentication
  81. Title Title Data Hash SHA1 ( $DATA ) Authentication

  82. None
  83. Title Title Prevent Abuse Maintain Availability Client Key IP Address

    User ID Rate Limiting
  84. None
  85. Title Title How to debug as you develop? CURL Automated

    Tests Rested on OSX Debugging
  86. Go Make Cool Things

  87. 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
  88. 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
  89. Q/A

  90. Title Title Resources Give Me $$$ SecuringPhpApps.com SecuringNodeApps.com

  91. Ben Edmunds @benedmunds http://benedmunds.com https://joind.in/talk/52039 THANKS!