REST More With JSON-API (VarnaConf 2017)

REST More With JSON-API (VarnaConf 2017)

Covers what is an open standard, what standards we use in our day to day work. Describes in detail what JSON-API is and how utilizing it can help us build more maintainable and easier to consume APIs.

@ VarnaConf 2017

807dcecdfca0e4078d89127cd440c039?s=128

Boyan Yordanov

August 26, 2017
Tweet

Transcript

  1. VarnaConf 2017 REST MORE WITH JSON:API AND FRACTAL Use open

    standards to build better and more maintainable APIs 1
  2. $> WHOAMI $> BOYAN Developer at Shtrak Community cheerleader Newbie

    speaker and writer Organizer of PHP Varna 2 . 1
  3. WHERE TO FIND ME @specter_bg boyanyordanov boyanyordanov 2 . 2

  4. WHAT IS REST ? REpresentational State Transfer 3 . 1

  5. WHAT IS REST ? pretty URLs ? HTTP verbs for

    actions ? None of those ? 3 . 2
  6. ACHIEVING ETERNAL GLORY https://martinfowler.com/articles/richardsonMaturityMo 3 . 3

  7. HOW OFTEN DO YOU SEE POST /article/1/delete POST /article/1/publish GET

    /get-published-articles 3 . 4
  8. OR EVEN WORSE GET /REST/article/create?title="No REST from bad design" 3

    . 5
  9. SO ARE WE ... ? ... probably NOT. But does

    it really matter? 3 . 6
  10. OPEN STANDARDS What makes an open standard ? Cooperation Adherence

    to Principles Due process, Broad concensus, Transparency, Balance, Openness Collective Empowerment Availability Voluntary Adoption 4 . 1
  11. EXAMPLES WE USE EVERYDAY HTTP CSS, HTML, ECMAScript C, C++,

    Java ( ), C# PHP RFC process and PHP-Fig PSRs (sort of) JCP 4 . 2
  12. OPEN STANDARDS AND APIS Auth and security Oauth 1/2, OpenID

    Connect, JWT Documentation / helper openapi/swagger, api blueprint, RAML, json- schema Representation / content types HAL, Problem JSON, Hydra and json-ld, JSON-API Other GraphQL 5
  13. BENEFITS OF USING STANDARDS FOR APIS easier to design and

    build easier to maintain easier to consume easier to test 6 . 1
  14. 6 . 2

  15. 7

  16. OVERVIEW well-de ned conventions for listing, creating, updating and deleting

    resources recommendations for details not covered in the main spec server and client libraries in most popular languages 8
  17. http://www.commitstrip.com/en/2017/02/20/no-ones- fault/ 9

  18. { "data": { "type": "articles", "id": "1", "attributes": { "title":

    "JSON API paints my bikeshed!" }, "relationships": { "author": { "links": {"self": "...", "related": "..."}, "data": { "type": "people", "id": "9" } } }, "links": { "self": "/articles/1"} } } 10
  19. THE MEDIA TYPE Client call Server response Accept: application/vnd.api+json Content-Type:

    application/vnd.api+json Content-type: application/vnd.api+json 11 . 1
  20. DECONSTRUCTING THE COMPOUND DOCUMENT TOP LEVEL ATTRIBUTES data errors meta

    links jsonapi included 11 . 2
  21. TYPES OF OBJECTS resource object link object resource identi er

    object error object 12 . 1
  22. THE RESOURCE OBJECT { "type": "meetups", "id": "1", "attributes": {

    "name": "PHP Varna", "description": "The php UG of Varna", "next-event": "2017-05-18T19:30:00.200Z" } } 12 . 2
  23. LINKS OBJECT "links": { "self": "/meetups/1" }, "data": { ...

    } 12 . 3
  24. "data": { ... }, "relationships": { "links": { "events": {

    "related": "/meetups/1/events", "meta": { "count": 50 } } } } 12 . 4
  25. RESOURCE IDENTIFIER OBJECT { "id": "1", "type": "events", "meta": {

    "attendee-count": 50 } } 12 . 5
  26. RELATIONSHIPS OBJECT "relationships": { "location": { "links": { "self": "events/1/relationships/venue",

    "related": "events/1/venue" }, "data": { "type": "venues", "id": "1" } } } 12 . 6
  27. PUTTING IT ALL TOGETHER GET /meetups HTTP/1.1 Accept: application/vnd.api+json {

    "data": [{ "type": "meetups", "id": "1", "attributes": { "name": "PHP Varna", "description": "The php UG of Varna", "next-event": "2017-05-18T19:30:00.200Z" }, "relationships": { "organizer": { "data": { "type": "users", "id": "1" } } } }] } 13
  28. RELATIONSHIPS Change the meetup place PATCH /events/123/relationships/venue HTTP/1.1 Content-Type: application/vnd.api+json

    Accept: application/vnd.api+json { "data": { "type": "venues", "id": "12" } } 14 . 1
  29. Remove the venue (untill we nd a new one?) PATCH

    /events/123/relationships/venue HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/vnd.api+json { "data": null } 14 . 2
  30. SIDELOADING RELATIONSHIPS (GET MEETUP AND VENUE) GET /events/1?include=venue HTTP/1.1 HTTP/1.1

    200 OK Content-Type: application/vnd.api+json { "data": { // resource object for the event }, "included": [ { "type": "venues", "id": "1", "attributes": { "name": "VarnaLab", "address": "ul. 'Pencho Slaveykov' 50" } } ] 14 . 3
  31. ERROR OBJECTS HTTP/1.1 422 Unprocessable Entity Content-Type: application/vnd.api+json { "errors":

    [ { "status": "422", "source": { "pointer": "/data/attributes/name" }, "title": "Invalid Attribute", "detail": "Meetup name must contain at least three characters." } ] } 15
  32. QUERY PARAMS ltering sorting GET /meetups?filter[location]="Varna" HTTP/1.1 Accept: application/vnd.api+json GET

    /meetups?sort=name HTTP/1.1 Accept: application/vnd.api+json GET /meetups?sort=-name HTTP/1.1 Accept: application/vnd.api+json 16 . 1
  33. sparse eldsets GET /meetups?fields[meetups]=name HTTP/1.1 Accept: application/vnd.api+json { "data": [

    { "id": "1", "type": "meetups", "attributes": { "name": "PHP Varna" } }, { "id": "2", "type": "meetups", "attributes": { "name": "WordPress Varna" } } 16 . 2
  34. COMPLEX QUERY GET /events?filter[meetup]="PHP Varna" &filter[venue]="VarnaLab" &filter[date_after]="26-08-2017" &include=venues &fields[events]=name,date &fields[venues]=address

    HTTP/1.1 Accept: application/vnd.api+json 16 . 3
  35. PAGINATION GET /meetups?page[number]=3&page[size]=1 HTTP/1.1 Accept: application/vnd.api+json 16 . 4

  36. { "meta": { "total-pages": 12 }, "data": [ { "type":

    "meetups", "id": "2", "attributes": { "name": "WordPress Varna", "description": "The place for WordPress entusiasts", "next-meetup": "", } } ], "links": { "self": "/meetups?page[number]=2&page[size]=1", "first": "/meetups?page[number]=1&page[size]=1", "prev": "/meetups?page[number]=2&page[size]=1", "next": "/meetups?page[number]=4&page[size]=1", "last": "/meetups?page[number]=12&page[size]=1" } } 16 . 5
  37. RESOURCE OPERATIONS listing get individual resource create update delete 17

  38. CREATE A MEETUP POST /meetups HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/vnd.api+json

    { "data": { "type": "meetups", "attributes": { "name": "JS Varna?", "desription": "Does Varna need another meetup?" }, "relationships": {//optional} } } 18 . 1
  39. RESPONSE HTTP/1.1 200 OK Content-Type: application/vnd.api+json { "data": { "type":

    "meetups", "id": 3, "attributes": { "name": "JS Varna?", "desription": "Does Varna need another meetup?" } } } 18 . 2
  40. UPDATING A MEETUP PATCH /meetups/3 HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/vnd.api+json

    { "data": { "type": "meetups", "attributes": { "name": "JS Varna", "desription": "Happening soon in a hackerspace near you" } } } 18 . 3
  41. CANCELING AN EVENT RESPONSE DELETE /events/123 Content-Type: application/vnd.api+json Accept: application/vnd.api+json

    HTTP/1.1 204 No Content Content-Type: application/vnd.api+json 18 . 4
  42. A 404 ERROR RESPONSE GET /meetups/1234 Content-Type: application/vnd.api+json Accept: application/vnd.api+json

    HTTP/1.1 404 Not Found Content-Type: application/vnd.api+json { "errors": [ { "title": "Resource Not Found", "content": "There is no event with id 1234" } ] } 18 . 5
  43. FRACTAL Like a view layer for your JSON/YAML/etc. 19

  44. MAIN CONCEPTS Fractal Manager Resource Includes Serializer Transformer Pagination via

    paginator via cursor 20
  45. RESOURCES & TRANSFORMERS Closure transformer use League\Fractal\Resource\Item; $meetup = retrieveFromDB();

    $meetupResource = new Item($meetup, function($m) { return [ 'id' => $meetup->id, 'name' => $meetup->name, 'description' => $meetup->description, 'next-meetup' => $meetup->events->getNext()->date ]; }); 21 . 1
  46. Class transformer use League\Fractal\TransformerAbstract; use League\Fractal\Resource\Collection; class MeetupTransformer extends TransformerAbstract

    { public function transform(Meetup $meetup) { return [ 'id' => $meetup->id, 'name' => $meetup->name, 'description' => $meetup->description, 'next-meetup' => $meetup->events->getNext()->date ]; } } $data = new Collection($meetups, new MeetupTransformer); 21 . 2
  47. De ning includes use League\Fractal\TransformerAbstract; use League\Fractal\Resource\Collection; class MeetupTransformer extends

    TransformerAbstract { protected $availableIncludes = ['venues']; public function transform($meetup) { ... } public function includeVenue($meetup) { $venue = $meetup->venue; $transformer = new VenueTransformer; return $this->item($venue, $transformer, 'venues'); } } $data = new Collection($meetups, new MeetupTransformer); 21 . 3
  48. Creating a resource use League\Fractal\Serializer\JsonApiSerializer; $manager = new League\Fractal\Manager(); $baseUrl

    = 'http://meetup.dev'; $manager->setSerializer(new JsonApiSerializer($baseUrl)); // ORM call $meetup = Meetup::find(1); // Make a resource out of the data and $resource = new Item($meetup, new MeetupTransformer, 'meetups'); // Run all transformers $manager->createData($resource)->toArray(); 21 . 4
  49. Result [ "data" => [ "type" => "meetups", "id" =>

    "1", "attributes" => [ "name" => "PHP Varna", "description" => "The php UG in Varna", "next-meetup" => "2017-05-18T19:30:00.200Z" ] ], "links" => [ "self" => "http://meetup.dev/meetups/1" ] ] 21 . 5
  50. Using includes use League\Fractal\Serializer\JsonApiSerializer; $manager = new League\Fractal\Manager(); $baseUrl =

    'http://meetup.dev'; $manager->setSerializer(new JsonApiSerializer($baseUrl)); // ORM call $meetup = Meetup::find(1); if (isset($_GET['include'])) { $fractal->parseIncludes($_GET['include']); } 21 . 6
  51. WHAT IS MISSING FROM THE SPEC? ltering sorting sparse eldsets

    pagination - present and usable but not spec compliant 22 . 1
  52. PAGINATION use League\Fractal\Resource\Collection; use League\Fractal\Pagination\IlluminatePaginatorAdapter; use Acme\Model\Book; use Acme\Transformer\BookTransformer; $paginator

    = Meetup::paginate(); $meetups = $paginator->getCollection(); $resource = new Collection($meetups, new MeetupTransformer); $resource->setPaginator(new IlluminatePaginatorAdapter($paginator)); 22 . 2
  53. SUPPORTED ADAPTERS Laravel Doctrine Zend Framework Phalcon Pagerfanta your own

    PaginatorInterface implementation 22 . 3
  54. WHAT IS NOT INCLUDED ON PURPOSE? content negotiation response code

    handling error objects 22 . 4
  55. HANDLING ERROR OBJECTS 23

  56. Use a base class class JsonApiError extends \Exception { protected

    $status; protected $title; protected $detail; protected $source; protected $meta; public function toArray() {...} } 24 . 1
  57. Extend it for speci c errors class NotFoundError extends JsonApiError

    { protected $status = 404; protected $title = 'Resource not found'; } 24 . 2
  58. EASIER FRACTAL composer install spatie/fractalistic A developer friendly wrapper around

    Fractal 25 . 1
  59. Fractal::create() ->collection($meetups) ->transformWith(new MeetupTransformer()) ->includeVenue() ->toArray(); 25 . 2

  60. ALTERNATIVES neomerx/json-api resource transformation query parameters handling errors 26

  61. RESOURCES http://jsonapi.org/ http://fractal.thephpleague.com/ https://www.ics.uci.edu/~ elding/pubs/dissertation/ e Steve Klabnik's talk: past,

    present and future of json-ap https://youtu.be/Foi54om6oGQ discussion: who's using json-api - https://github.com/jso api/issues/825 27
  62. THANK YOU 28

  63. QUESTIONS ? 29