Downloaded 14 times
Uploaded byAndrew Curioso
NEPHP '13: Pragmatic API Development
This document discusses best practices for developing pragmatic APIs. It covers topics such as defining API resources as nouns and using HTTP verbs to manipulate them, following REST principles, using JSON and status codes effectively, implementing authentication, authorization, versioning, pagination and error handling, and testing and documenting APIs. The document emphasizes designing the API schema upfront, using consistent URIs and formats, and proper testing and documentation. It predicts APIs will be important for connecting devices and powering the emerging "API economy".
NEPHP '13: Pragmatic API Development
- 1. Andrew Curioso Twitter: @AndrewCurioso #nephp PragmaticAPI Development Andrew Curioso
- 2. What is anAPI? ● Application Programming Interface ● Web Service ● Contract
- 3. Business Case ● MobileAPI First
- 4. Business Case ● MultipleDevices Your API
- 5. Become a Platform ●Internal – Multi-platform – Scalable ● Semi-Public – Partner Integration ● Public – Everything+ – Growth ● Mashups ● Innovation ● Evangelism – “The Platform Play”
- 6. Types of APIs ●Representation StateTransfer (REST) ● Remote Procedure Call (RPC) ● Realtime Streaming
- 7. What is REST? ●Nouns ● Verbs ● HTTP is inherently RESTful
- 8. Why REST ● Intuitive ●Easy to implement in PHP ● Widely accepted
- 9. Nouns ● Resources – Blogpost – User – Etc. ● Unique URIs – Example: http://www.example.com/users/1234.json
- 10. Verbs ● 5 mostcommon – GET – POST – PUT – DELETE – HEAD
- 11. Verbs ● Uses – GET– Read data – POST and PUT write data – DELETE and POST delete data
- 12. CSRF ● Cross SiteRequest Forgery ● Vectors: – Embedded resources (<img>, <script>, etc) – Hidden forms security
- 13. CSRF ● Never editdata with GET – Ajax Same origin policy→ ● Forms – Single use tokens – Referrer check security
- 14. Response Formats ● Json –Very common for REST APIs – Simple – Fast – Multi-platform
- 15. Response Formats ● JsonP –P Padding→ – Allows reading data cross origin – GET only
- 16. Response Formats ● XML –Heavy and verbose – Strictly typed – Lots of existing tools
- 17. Response Formats ● Text –Json / JsonP – XML – HTML – YAML – CSV – Serialized PHP – Etc. ● Binary – Microsoft Excel – PDF – JPG / PNG / GIF – MP3 – Etc.
- 18. Status Codes ● Success –200 OK – 201 Created – 301 Permanent Redirect – 302 Found – 303 See Other
- 19. Status Codes ● Error –401 Unauthorized – 402 Payment Required – 403 Forbidden – 404 Not Found – 405 Method NotAllowed – 409 Conflict – 410 Gone – 500 Internal Server Error – 501 Not Implemented – 503 Service Unavailable
- 20. Status Codes ● Novelty –418 I Am ATeapot – 415 Unavailable For Legal Reasons
- 21. Putting it together ●Getting – Anything but GET ● 405 Method Not Allowed – Resource not found ● 404 Not Found – Success ● 200 OK – Moved ● 301 Permanent Redirect or 302 Found
- 22. Putting it together ●Adding – Anything but POST ● 405 Method Not Allowed – Resource already existed ● 303 See Other – Success ● 201 Created – Error ● 500 Internal Server Error with description
- 23. Putting it together ●Editing – Anything but PUT or POST ● 405 Method Not Allowed – Resource does not exist ● 404 Not Found – Success ● 200 OK – Error ● 500 Internal Server Error with description
- 24. Putting it together ●Deleting – Anything but DELETE or POST ● 405 Method Not Allowed – Resource does not exist ● 404 Not Found – Success ● 200 OK or 204 No Content – Error ● 500 Internal Server Error with description
- 25. Putting it together ●Everything – Not logged in ● 401 Unauthorized – Logged in but permission denied ● 403 Forbidden
- 26. Putting it together ●Why POST or DELETE/PUT – Client support – _method=VERB ● /users.json?_method=POST
- 27. Example ● Past bin ●Simple – No security
- 28. Example ● Making itRESTful 1) Identify nouns 2) Write down URI structure 3) Map verbs to the URIs
- 29. Example ● GET /documents.json ●POST /documents.json ● GET /documents/{id}.json ● DELETE /documents/{id}.json ● PUT /documents/{id}.json
- 30. HATEOAS ● Hypermedia asthe Engine of Application State – Next state – Content Negotiation ● Accepts header
- 31. Versioning ● URI ● Customheader ● Accepts header
- 32. Pagination ● Meta info –URI to next/prev page (HATEOAS) – Total count – Current page ● Methods – Header – Document
- 33. Errors ● Same format ●Descriptive { "error" : { "code" : 404, "description" : "The resource could not be found", "name" : "Not Found" } }
- 34. Testing ● GET WebBrowser→ ● OS X / Linux – curl – Example: curl -X DELETE “ http://www.example.com/document/123.json” ● Automated UnitTests
- 35. Authentication ● Who amI? ● Types: – Basic – Digest – OAuth 1 & 2 – No 3rd party password sharing! – Cookies – API keys ● 401 Unauthorized
- 36. Authorization ● Can Ido that? ● 403 Forbidden
- 37. Documentation ● Vocabularies /schemas ● Examples: – Input – Output – Code ● Feedback ● WSDL 2.0
- 38.
- 39. Checklist ✔ Design schemaupfront ✔ Identify nouns ✔ Design URI structure ✔ Errors in same format ✔ Proper status codes ✔ Server-side validation ✔ Testing ✔ Documentation
- 40. Predictions ● Internet ofThings ●API Economy ● Success
- 41. Andrew Curioso Contact: www.AndrewCurioso.com/contact @AndrewCurioso onTwitter
Editor's Notes
- #2 Thank you _____________ Today I’m going to be talking about creating a RESTful API with PHP. Not just any RESTful API, but an Epic one. &lt;number&gt;