How JSON-API Can Bring Sanity to Your PHP APIs

Presented at NomadPHP, September 2015: https://www.youtube.com/watch?v=qSDfrITkvjo

APIs are everywhere: many return JSON and are RESTful or even provide hypermedia controls, but chances are they do not adhere to any standard. Essentially they all speak a different language that has to be learned for each specific provider. Wouldn’t it be great if there was a sane specification that lets you standardize your API? Something around which the community can build tools so you don’t have to reinvent the wheel over and over again? In this talk I will introduce the JSON-API specification and explain how it can benefit you on your next API project.

Transcript

1. HOW JSON-API CAN BRING SANITY TO YOUR PHP APIs
2. HENNING GLATTER-GÖTZ @hglattergotz
3. Podcasting at ... REACTIVE.AUDIO Panel discussions about current tech news with a focus on JavaScript
4. ... and also podcasting at DESCRIPTIVE.AUDIO Programmer origin stories
5. MY APIs ARE NOT INSANE!
6. REST IS VERY FLEXIBLE
7. WHAT IS SO BAD ABOUT THAT??
8. bikeshedding
9. SEVERAL ATTEMPTS TO SOLVE THIS EXIST HAL, Siren, OData, JSON-API
10. COVERED BY JSON-API SPEC Content Negotiation Document Structure Fetching Data Creating, Updating and Deleting Resources Query Parameters Errors
11. CONTENT NEGOTIATION Content-Type: application/vnd.api+json
12. DOCUMENT STRUCTURE
13. SINGLE RESOURCE { "data": { "type": "articles", "id": "1", "attributes": { "title": "Hello world", "body": "bla bla bla" } } }
14. SINGLE RESOURCE WITH RELATIONSHIP { "data": { "type": "articles", "id": "1", "attributes": { "title": "Hello world", "body": "bla bla bla" }, "relationships": { "author": { "links": { "self": "http://example.com/articles/1/relationships/author", "related": "http://example.com/articles/1/author" }, "data": { "type": "people", "id": "9" } } } }, "included": [] }
15. FETCHING DATA - SPARSE FIELD SETS GET /articles?fields[articles]=title,body HTTP/1.1 Accept: application/vnd.api+json
16. FETCHING DATA - SORTING ascending GET /articles?sort=created HTTP/1.1 descending GET /articles?sort=-created,title HTTP/1.1
17. ERRORS HTTP/1.1 422 Unprocessable Entity Content-Type: application/vnd.api+json { "errors": [ { "status": "422", "source": { "pointer": "/data/attributes/first-name" }, "title": "Invalid Attribute", "detail": "First name must contain at least three characters." } ] }
18. SO HOW DOES ANY OF THIS HELP US?
19. tooling
20. CLIENT LIBRARIES PHP, JavaScript, iOS, Ruby
21. SERVER LIBRARIES PHP, Node.js, Ruby, Python, Go, .NET, Java
22. PHP SERVER LIBRARIES * GOintegro/HATEOAS - Symfony 2 /Doctrine 2 * tobscure/json-api * neomerx/json-api - framework agnostic * neomerx/limoncello-collins Laravel-based quick start server * lode/jsonapi * woohoolabs/yin * nilportugues/json-api * nilportugues/symfony2-jsonapi-transformer - Symfony 2 * nilportugues/laravel5-jsonapi-transformer - Laravel 5
23. QUICK LOOK AT neomerx/json-api
24. HAND CRAFTED // Lots of hand written code here // : // to manually build array representation of document structure return json_encode($data);
25. NEOMERX/JSON-API 01 $encoder = Encoder::instance([ 02 ArticleModel::class => ArticleSchema::class 03 AuthorModel::class => AuthorSchema::class 04 ], 05 new EncoderOptions($encodeOptions, 'http://example.com') 06 ); 07 08 return $encoder->encodeData($articles);
26. Thank You! @hglattergotz