building awesome apis with lumen
TRANSCRIPT
![Page 1: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/1.jpg)
Building Awesome APIs with Lumen
Kit Brennan Rokk3r Labs
![Page 2: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/2.jpg)
• Consistent
• Reliable
• Easy to use
What makes an API awesome Overview
![Page 3: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/3.jpg)
• Super fast out the box
• If you know Laravel, you know Lumen
• All of Laravel waiting to be switched on
Why Lumen Overview
![Page 4: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/4.jpg)
• Requests
• Responses
• Logging
• Documentation
• Testing
Structure of the talk Overview
![Page 5: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/5.jpg)
• Version your API using route prefixes
Routing Requests
![Page 6: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/6.jpg)
• Also, an excellent use of subdomain routing:
Routing Requests
![Page 7: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/7.jpg)
• Create an /api/1/ping route for public APIs
• Don’t put any middleware in front of the route
• Two reasons:
• Lets clients easily check if server is up
• First step of integrating with an API is just making sure your request reaches the remote server.
Routing Requests
![Page 8: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/8.jpg)
• Choose an endpoint structure and stick to it
• Have awesome documentation for all endpoints we will come back to this
• GET is a safe method this should really go without saying
• PUT and DELETE are idempotent operation should always produce same result
Routing Requests
![Page 9: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/9.jpg)
• GET https://example.com/api/1/users
• POST https://example.com/api/1/users
• GET https://example.com/api/1/users/1
• PUT https://example.com/api/1/users/1
• DELETE https://example.com/api/1/users/1
Routing Requests
![Page 10: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/10.jpg)
• https://github.com/barryvdh/laravel-cors
• Public APIs: allow all origins
• Private APIs: allow your origins
CORS Requests
![Page 11: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/11.jpg)
• Session based authentication not appropriate
• Three options:
• Access token authenticationfor server-server apps - you provide token in advance
• JSON web tokenfor client-side apps - you provide a token at user login
• Oauthfor third party apps accessing existing user accounts on your system
Authentication methods Requests
![Page 12: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/12.jpg)
• https://github.com/tymondesigns/jwt-auth
• Scales much better than other options - each server validates the token, rather than making a DB call
• Frontend apps should store the token with LocalStorage
• Tokens should expire use refresh tokens to generate new tokens
Authentication - JSON web tokens Requests
![Page 13: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/13.jpg)
• https://github.com/lucadegasperi/oauth2-server-laravel
• Potentially very dangerous (so get it right):
• You’re giving someone access to client data
• Read the spec: http://tools.ietf.org/html/rfc6749
Authentication - Oauth Requests
![Page 14: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/14.jpg)
• Avoid the magic controller validation
• Instead create a validation class, call it and check in your controller if it fails
Validation Requests
![Page 15: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/15.jpg)
• Awesome APIs accept many date formats
• Validation facades date validator uses strtotime
• Carbon’s parse method uses strtotime
• Combine the two and you can safely accept any date
• Caveat… a unix timestamp is not parsed by strtotime
Dates Requests
![Page 16: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/16.jpg)
• Even APIs should have a view layer
• Explicitly cast all types
Transformers Responses
![Page 17: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/17.jpg)
• Do not forget to transform your Carbon objects
Transformers Responses
![Page 18: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/18.jpg)
• Use a transformer package
• https://github.com/salebab/larasponsethe documentation sucks, but it’s still the best package
• You provide a class with a transform method, then simply call it in any controller:
Transformers Responses
![Page 19: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/19.jpg)
• Power comes when you want to include other transforms in your transformer (transformer class)
• Always include with a transformer (transformer class):
• Or optional include (controller class):
Transformers Responses
![Page 20: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/20.jpg)
• Response macros let you include additional meta data to response
• Macros also ensure consistency of base response across all response statuses and all endpoints
• Register in a service provider:
Response Macros Responses
![Page 21: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/21.jpg)
• Log all requests and all responses
• This is 10x as true if you are making a public API
• Make your logs easily accessible no, SSHing into a server is not easily accessible
When to log Logging
![Page 22: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/22.jpg)
• Shameless plug for today’s sponsor: www.understand.ioprobably the best option, so not such a shameless plug
• Anything supported by Monolog should work out the box
• https://papertrailapp.com
• https://www.loggly.com
• The ELK stack https://www.elastic.coopen source
Logging services Logging
![Page 23: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/23.jpg)
• One is auto documented, one isn’t:
Auto documenters Documentation
![Page 24: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/24.jpg)
• http://readme.io/
• https://apiary.io/
• https://www.mashape.com/
• http://swagger.io/ -> popular auto documenter
• GitHub/Bitbucket wikis
Documentation services Documentation
![Page 25: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/25.jpg)
• Tell developers about any breaking API changes
• Give 30 days notice of breaking changes or downtimeideally longer
• Make it super clear you won’t use the mailing list for marketing
• Never use the mailing list for marketing
Mailing list Documentation
![Page 26: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/26.jpg)
• Write full end to end API tests. Lumen supports these out the box:
API tests Testing
![Page 27: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/27.jpg)
• Statically define your test expectations for a given routeyour seeder will need to have some fixtures for this
Test every field Testing
![Page 28: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/28.jpg)
• Returning a 200 when you should be returning a 403 (forbidden) is inexcusable.
Test failures Testing
![Page 29: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/29.jpg)
• In your TestCase.php
JWT Override Testing
![Page 30: Building Awesome APIs with Lumen](https://reader031.vdocuments.mx/reader031/viewer/2022030301/587fd7b21a28ab58248b5b7b/html5/thumbnails/30.jpg)
Thank You
Kit Brennan Rokk3r Labs