Building Awesome APIs with Lumen

Kit Brennan Rokk3r Labs

• Consistent

• Reliable

• Easy to use

What makes an API awesome Overview

• Super fast out the box

• If you know Laravel, you know Lumen

• All of Laravel waiting to be switched on

Why Lumen Overview

• Requests

• Responses

• Logging

• Documentation

• Testing

Structure of the talk Overview

• Version your API using route prefixes

Routing Requests

• Also, an excellent use of subdomain routing:

Routing Requests

• 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

• 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

• 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

• https://github.com/barryvdh/laravel-cors

• Public APIs: allow all origins

• Private APIs: allow your origins

CORS Requests

• 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

• 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

• 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

• Avoid the magic controller validation

• Instead create a validation class, call it and check in your controller if it fails

Validation Requests

• 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

• Even APIs should have a view layer

• Explicitly cast all types

Transformers Responses

• Do not forget to transform your Carbon objects

Transformers Responses

• 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

• 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

• 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

• 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

• 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

• One is auto documented, one isn’t:

Auto documenters Documentation

• http://readme.io/

• https://apiary.io/

• https://www.mashape.com/

• http://swagger.io/ -> popular auto documenter

• GitHub/Bitbucket wikis

Documentation services Documentation

• 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

• Write full end to end API tests. Lumen supports these out the box:

API tests Testing

• Statically define your test expectations for a given routeyour seeder will need to have some fixtures for this

Test every field Testing

• Returning a 200 when you should be returning a 403 (forbidden) is inexcusable.

Test failures Testing

• In your TestCase.php

JWT Override Testing

Thank You

Kit Brennan Rokk3r Labs