Creating Awesome Web APIs is a Breeze

8,641 views

Published on

Presented at the O'Reilly Open Source Conference 2014 (OSCON) in Portland, OR, USA and a slight variation thereof at APIcon UK in London, UK.

Published in: Engineering, Technology

Creating Awesome Web APIs is a Breeze

  1. { "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" } http://example.com/events/oscon2014
  2. http://example.com/events/oscon2014 { 69 64: 6F 73 63 6F 6E 32 30 31 34 0D, 74 79 70 65: 45 76 65 6E 74 0D, 6E 61 6D 65: 4F 53 43 4F 4E 0D, 64 65 73 63 72 69 70 74 69 6F 6E: 4F 27 52 65 69 6C 6C … 73 74 61 72 74 44 61 74 65: 32 30 31 34 2D 30 37 2D 32 … 65 6E 64 44 61 74 65: 32 30 31 34 2D 30 37 2D 32 34 54 … 6C 6F 63 61 74 69 6F 6E: 4F 72 65 67 6F 6E 20 43 6F 6E … 6F 72 67 61 6E 69 7A 65 72: 4F 27 52 65 69 6C 6C 79 0D }
  3. http://example.com/events/oscon2014 { "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  4. http://example.com/events/oscon2014 { "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  5. http://example.com/events/oscon2014 { "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  6. http://example.com/events/oscon2014 { "@context": { "name": "http://schema.org/name", "description": "http://schema.org/description", "startDate": "http://schema.org/startDate", ... }, "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  7. http://example.com/events/oscon2014 "@context": { "@vocab": "http://schema.org/" }, "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  8. http://example.com/events/oscon2014 "@context": { "@vocab": "http://schema.org/" }, "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  9. http://example.com/events/oscon2014 "@context": { "@vocab": "http://schema.org/" }, "@id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  10. http://example.com/events/oscon2014 "@context": { "@vocab": "http://schema.org/" }, "@id": "oscon2014", "@type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  11. http://example.com/events/oscon2014 { "@context": { "@vocab": "http://schema.org/", "startDate": { "@type": "DateTime" } }, "@id": "oscon2014", "@type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  12. http://example.com/events/oscon2014 { "@context": { ... "startDate": { "@type": "DateTime" } "id": "@id", "type": "@type" }, "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  13. http://example.com/events/oscon2014 { "@context": "/contexts/event.jsonld", "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  14. http://example.com/events/oscon2014 { "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  15. http://example.com/events/oscon2014 HTTP/1.1 200 OK Content-Type: application/json Link: </contexts/event.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" { "id": "oscon2014", "type": "Event", "name": "OSCON", "description": "O'Reilly Open Source Convention 2014", "startDate": "2014-07-20T16:00:00Z", "endDate": "2014-07-24T21:00:00Z", "location": "Oregon Convention Center", "organizer": "O'Reilly" }
  16. <script type="application/ld+json"> ... </script>
  17. http://example.com/events/ { "@id": "/events/", "@type": "Collection", "member": [ ... ], ... "operation": { "@type": "http://schema.org/AddAction", } }
  18. { "@id": "Event", "@type": "Class", "supportedProperty": { "property": "name", "required": true } } http://example.com/events/ { "@id": "/events/", "@type": "Collection", "member": [ ... ], ... "operation": { "@type": "AddAction", "method": "POST", "expects": "Event" } }
  19. { "@id": "Event", "@type": "Class", "supportedProperty": { "property": "name", "required": true } } http://example.com/events/ { "@id": "/events/", "@type": "Collection", "member": [ ... ], ... "operation": { "@type": "AddAction", "method": "POST", "expects": "Event" } }
  20. { "@id": "Event", "@type": "Class", "supportedProperty": { "property": "name", "required": true } } http://example.com/events/oregon/ { "@id": "/events/oregon/", "@type": "Collection", "member": [ ... ], ... "operation": { "@type": "AddAction", "method": "POST", "expects": "Event" } }
  21. http://example.com/events/oregon/ { "@id": "/events/oregon/", "@type": "Collection", "member": [ ... ], ... } { "@type": "AddAction", "method": "POST", "expects": "Event" }
  22. { "@id": "EventCollection", "@type": "Class", "subClassOf": "Collection", "supportedOperation": { "@type": "AddAction", "method": "POST", "expects": "Event" } } http://example.com/events/oregon/ { "@id": "/events/oregon/", "@type": "EventCollection", "member": [ ... ], ... } { "@type": "AddAction", "method": "POST", "expects": "Event" }
  23. /** * Event * * @HydraExpose(iri="http://schema.org/Event") * @HydraId("event_retrieve") * @HydraOperations( { * "event_replace", * "event_delete" * } ) */ class Event { /** * The event's name * * @HydraExpose(iri="http://schema.org/name", required=true) */ private $name; // ... other members and methods ... }
  24. $ php app/console hydra:generate:crud --entity=MLEventApiBundle:Event --route-prefix=/events/ --with-write --no-interaction CRUD generation Generating the CRUD code: OK You can now start using the generated code!
  25. /** * Event controller * * @Route("/events") */ class EventController extends HydraController { /** * Creates a new Event entity * * @Route("/", name="event_create") * @Method("POST") * * @HydraOperation( * type = "http://schema.org/AddAction", * expect = "MLEventApiBundleEntityEvent" * }) * * @return MLEventApiBundleEntityEvent */ public function collectionPostAction(Request $request) { ...

×