An API Your Parents Would Be Proud Of

An API your parents would be proud of!!!

@[email protected]

https://www.linkedin.com/pub/jose-alfredo-alvarez-aldana/25/47b/b62FIT Universidad Galileo, Guatemala

10/9/2014 https://db.tt/DscxrOCk 1

mailto:[email protected]

https://www.linkedin.com/pub/jose-alfredo-alvarez-aldana/25/47b/b62

Agenda

• API super summary

• Vagrant– Puppet

• API

• Symfony (PHP Framework)– FOSRestBundle

• BeerCount (act surprised)

• Angular

• Recommendations


http://github.com/FriendsOfSymfony/FOSRestBundle


API

• “In computer programming, an application programming interface (API) specifies a software component in terms of its operations, their inputs and outputs and underlying types.” --Wikipedia


API

• It’s not easy … for realz :S

• Lots of theory and rules

– But we like to break the rules :P

• Open to interpretation (sometimes)


But first …

• Let me take a selfie?


But first …

• Let me take a selfie?

• Cool technologies from the block:



• “Create and configure lightweight, reproducible, and portable development environments.”

• http://www.vagrantup.com/


• “Puppet Labs is the leader in IT automation. Our software helps sysadmins

automate configuration and management of machines and the software running on them. With our

software, businesses can make rapid, repeatable changes and automatically enforce the consistency of systems and devices, across physical and virtual machines, on prem or in the cloud. We help tens of thousands of the world’s leading companies manage millions of machines and devices. Companies like Bank of America, Cisco, Citrix, eBay, NYSE, PayPal, and salesforce.com rely on our software to deploy their own software faster, be more productive, and gain insight into infrastructure configurations and operation. Based in Portland, Oregon, Puppet Labs employs more than 300 people. We’ve raised $86 million from our investors: Cisco, Google Ventures, Kleiner Perkins Caufield & Byers, Radar Partners, Triangle Peak Partners, True Ventures and VMware.”

• http://puppetlabs.com/


Uses for us?

• Local environment setup

– Consistent

– Rapid

– Automate installation

– Example … today, right now, FIT

• Team Collaboration


Vagrant DEMO

• git clone https://github.com/chepeftw/VagrantSimpleEnvSymfony.git

– Need help with that “git” sorcery?

https://www.codeschool.com/paths/git


https://www.codeschool.com/paths/git

Vagrant DEMO

$ git clone https://github.com/chepeftw/VagrantSimpleEnvSymfony.git

$ cd VagrantSimpleEnvSymfony

$ vagrant up

$ vagrant ssh

$ vagrant destroy -f




API

• URL structure?

• Json?

• Errors?

• Testing?

• HTTP methods?

• Status codes?

• Documentation?



API

• HTTP

– GET /drinkBeer

– HTTP/1.1 200 OK

…

<h1>Cheers!</h1>

http://tools.ietf.org/html/rfc2616


HTTP

• HTTP Request

GET /beer.html HTTP/1.1

Host: www.party.com

Accept: application/json

– /beer.html => Uniform Resource Identifier (URI)

– GET => HTTP Method

– HTTP Headers


HTTP

• HTTP ResponseHTTP/1.1 200 OK

Date: Mon, 23 May 2005 22:38:34 GMT

Server: Apache/1.3.3.7 (Unix) (Red-Hat/Linux)

Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT

<html><body> Hello Beer </body></html>

– 200 OK => HTTP Status Code

– HTTP Headers

– Body


REST

• http://www.ics.uci.edu/~taylor/documents/2002-REST-TOIT.pdf

• /beers

– Collection of resources of beers.

• /beers/cabro

– Single beer resource.


http://www.ics.uci.edu/~taylor/documents/2002-REST-TOIT.pdf

Representation

GET /beers/cabro

{

“id” : 1,

“name” : “cabro”

}


Representation

GET /beers/cabro

{

“id” : 1,


}


Json representationOf a beer Resoruce

Representation

• Machine-readable

• Current state of a resource


REST

• Rules on how two machines can transfer the state of a resource by using representations.


Richardson Maturity Model

• http://martinfowler.com/articles/richardsonMaturityModel.html


POST

• Creating resources*.

• HTTP Rule: After creating a resource, return a 201 status code.

• HTTP Rule: After creating a resource, return a Location header.

• Response should be a representation of the resource created.

• http://tools.ietf.org/html/rfc2616• * not exactly true but more information later



POST - request

POST /api/beers

{

“id” : 1,


“type” : “lager”

}


POST - response

HTTP/1.1 201 Created

Content-Type: application-json

Location: /api/beers/cabro

{

“id” : 1,



}


GET

• “Getting information”.

– Show a resource.

– List all resources.

• Retrieving a representation.

• 200 OK


GET- request

GET /api/beers


GET- response

HTTP/1.1 200 OK


{ “beers”: [{

“id” : 1,



}

]}


PUT

• “Updating/Editing” resources*.

• Meh!

• 200 OK

• No need for a Location header.


PUT - request

PUT /api/beers/cabro

{

“id” : 1,

“name” : “cabro reserva”


}


PUT - response

HTTP/1.1 200 OK


{

“id” : 1,



}


POST vs PUT

• Both unsafe HTTP methods (might change data).

• PUT is idempotent.

• POST is not idempotent.


DELETE

• Guess what it does? … Deletes a resource.

• 204 Status Code.


DELETE - request

DELETE /api/beers/cabro


GET- response

HTTP/1.1 204 No Content


QUICK NOTE

• HTTP Methods

– GET, POST, DELETE …

– Avoid:

• /api/beers/new

• /api/beers/delete

• /api/beers/list

• /api/beers/show


PATCH

• What about PUT?

– In theory, PUT should send ALL data to the server.

– It REPLACES ALL data (Bad PUT ).

• Eg. If you send just one property to “update”, in theory, it should put null in all the other properties.

• http://tools.ietf.org/html/rfc5789

• PATCH only updates the properties that are sent (Good PATCH ).



PUT - request

PUT /api/beers/cabro

{


}


FAIL DARKSSS!!!!!

PATCH - request

PATCH /api/beers/cabro

{


}


WIN!!!!

PATCH

• Ok … I lied :S

• PATCH is a set of instructions.


PATCH - request

PATCH /api/beers/cabro

{

{“op”: “replace”, ”path": ”name", "value": “cabro reserva”}

{“op”: “remove”, ”path": ”otherProperty”}

}


PATCH

• https://tools.ietf.org/html/rfc6902

• http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/


https://tools.ietf.org/html/rfc6902

http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/

ERRORS

• 400.

• 422: Unprocessable Entity?

• https://tools.ietf.org/html/draft-nottingham-http-problem-07

• Content-Type: application/problem+json


https://tools.ietf.org/html/draft-nottingham-http-problem-07

IANA Media Types

• http://www.iana.org/assignments/media-types/media-types.xhtml


http://www.iana.org/assignments/media-types/media-types.xhtml


• So what? Implementation?



• PHP Framework– MVC*

– CRUD

– Routes

– Controllers

– Templating

– Doctrine

– Testing

– Bla bla bla bla … http://symfony.com


• Tutorials? Help? Something?

– http://symfony.com/doc/current/book/index.html

– http://tutorial.symblog.co.uk/

– http://code.tutsplus.com/tutorials/diving-into-symfony-2--net-32923


http://symfony.com/doc/current/book/index.html

http://tutorial.symblog.co.uk/

http://code.tutsplus.com/tutorials/diving-into-symfony-2--net-32923

$ curl -s https://getcomposer.org/installer | php

$ php composer.phar create-project symfony/framework-standard-edition demo/ "2.5.*”

$ cd demo

$ php app/console generate:bundle

$ php app/console doctrine:generate:entity

$ php app/console doctrine:database:create

$ php app/console doctrine:schema:create

$ php app/console doctrine:generate:crud


• API?

– FOSRestBundle


DEMO!!!!


• Have you ever counted your friend’s beers? Or even yours? :O



Beer Count

The next generation super awesome cool web app, with this shagadelic state of the

art API ready for Angular and mobile Apps, that will help you keep count of how many

beers your friends have at a bar.

$ git clone [email protected]:chepeftw/BeerCountBeta.git



Angular

• MVC frontend

• Modules

• Controllers

• Services

• Data Binding

• http://campus.codeschool.com/courses/shaping-up-with-angular-js/intro


http://campus.codeschool.com/courses/shaping-up-with-angular-js/intro

Recommendations



Internet

An API Your Parents Would Be Proud Of