RESTful API-centric Universe

Orange Hill, BeogradTIHOMIR OPAČIĆ

RESTful API-centric Universe

https://leanpub.com/build-apis-you-wont-hate

Building APIs You Won’t Hate

PHIL STURGEON*

*founder of PyroCMS, Software Developer at Kapture

Web Facing mobile

aplikacije

iOS, Android…

RESTful API-centric UniverseGDE SE KORISTI RESTful API?

Javscript MVVM

Frameworks Angular JS, Ember, Backbone…


Google Glass API

https://developers.google.com/glass/v1/reference/


https://developers.google.com/glass/v1/reference/

Tesla Model S REST API

http://docs.timdorr.apiary.io/


Code on Demand

Layered System

Client-ServerCacheableStatelessUniform

Interface

REpresentational State Transfer

RESTful API-centric UniverseŠTA JE TO REST?

Arhitekturni model definisan u šest principa:

1 2 3 4 5 6

Uniformni interfejs definiše client-server komunikaciju na način da razdvaja ove dve celine (decoupling the architecture).

Ovo omogućava da se ove dve celine zasebno razvijaju.

Uniformni interfejs Uniform Interface1


Nepostojanje stanja je osnovna odlika REST arhitekture.

Svaki zahtev i odgovor servera na zahtev su jedinstvene nezavisne transakcije.

Nepostojanje stanjaStateless2


Klijent je slobodan da kešira podatke koje je primio kao odgovor servera, ukoliko server explicitno označi podatke da se mogu keširati.

Mogućnost keširanjaCacheable3


U interakciji klijenta i servera klijent ne vodi računa o čuvanju podataka, doke serveri ne vode računa o user interfejsu ili stanju klijenta.

Klijent-Server Client-Server4


Klijent nema načina da zna da li je povezan direktno na krajnji server. Ovaj princip omogućava skalabilnost servisa (load balancing, shared cache).

Slojeviti sistem Layered System5


Server je u mogućnosti da privremeno proširi mogućnosti klijenta da obavi određenu funkcionalnost tako što će mu preneti kod potreban za tu akciju, u vidu apleta ili skripti.

Kod na zahtev Code on Demand6


http://en.wikipedia.org/wiki/Representational_state_transfer

Servis koji se kreće u granicama REST principa naziva se RESTful servisom.

RESTful API-centric UniverseREST MODEL U WEB SERVISIMA

http://en.wikipedia.org/wiki/Representational_state_transfer

Karakteristike RESTful API servisa:

RESTful API-centric UniverseREST MODEL U WEB SERVISIMA

• koristi base URI, npr. http://example.com/resources/ • koristi Internet Media Type za prenos podataka.

Najčešće JSON (ili XML, Atom, microformats, images...) • koristi HTTP metode (npr. GET, PUT, POST ili DELETE) • koristi hypertext linkove da predstavi stanje (state) • koristi hypertext linkove da predstavi resurse

http://example.com/resources/

RESTful API-centric UniverseRESTful API SERVISI - PROBLEMI U PRAKSI

• Površni članci i knjige, često usmereni ka primeni na samo jednom framework-u

• Razvojni principi se često se mešaju sa SOAP RPC razvojnim principima

• Nedostatak standarda

REST/SOAP razlike:


• REST je arhitekturni model, SOAP je protokol (Glavni razlog nedostatka standarda)

REST/SOAP razlike:


REST koristi sledeće operacije HTTP protokola:

SOAP RPC programer birazvijao ovakve API metode:

• GET • POST • PUT • DELETE

• getUsers() • getNewUsersSince(SinceDate) • saveOrder(CID, PurchaseID)

RESTful API PROGRAMIRANJE

1 Dizajniranje baze podataka

RESTful API-centric UniverseBAZA PODATAKA

2 Popunjavanje baze podacima (Seeding)

Zašto je seeding bitan?

Seeding

RESTful API-centric UniverseSEEDING

“The process of creating seeding scripts means you don’t need to waste time creating this manually over and over again.”

• Acceptance testing • Podaci pravih korisnika ostaju poverljivi • Ne kopiramo podatke sa live servera na razvojne platforme

Programiranje Seeding skripti

Ušteda vremena potrebnogda se baza podataka popuni test podacima.

Faker


https://github.com/fzaninotto/Faker

"Faker is a PHP library that generates fake data for you.Faker is heavily inspired by Perl's Data::Faker, and by ruby's Faker."

https://github.com/fzaninotto/Faker

FakerRESTful API-centric UniverseSEEDING

Primer:

<?

$faker = Faker\Factory::create();

for ($i = 0; $i < Config::get('seeding.users'); $i++) { $user = User::create([ 'name' => $faker->name, 'email' => $faker->email, 'active' => $i === 0 ? true : rand(0, 1), 'gender' => rand(0, 1) ? 'male' : 'female' ]); }

Da li koristiti Random podatke za svaki Seeding proces?


Da li se Acceptance testovi oslanjaju na nepromenljive podatke u bazi?

iSeed


https://github.com/orangehill/iseed

"Inverse seed generator (iSeed) is a Laravel 4 package that provides a method to generate a new seed file based on data from the existing database table."

https://github.com/orangehill/iseed

iSeedRESTful API-centric UniverseSEEDING

Primeri:

$ php artisan iseed users

<?

\Iseed::generateSeed('users’);\Iseed::generateSeed(‘photos’);\Iseed::generateSeed(‘categories');

Endpoints Planning

RESTful API-centric UniverseENDPOINTS

Kreiranje spiska CRUD (Create, Read, Update, Delete) tačaka (endpoints) za resurse vaše aplikacije

Endpoints Planning

RESTful API-centric UniverseENDPOINTS

Users - Create - Read - Update - Delete - List (active, suspended) - Image

Posts - Create - Read - Update - Delete - List (approved, disapproved)

Naming ConventionBest Practices

GET resources

RESTful API-centric UniverseNAMING CONVENTIONS

•GET /users - Lista korisnika sa paginacijom •GET /users/X - Samo korisnik X. ID, hash, slug, username, ili neki

drugi podatak koji jedinstveno opisuje resurs •GET /users/X,Y,Z - Podaci o tri korisnika

•GET /users/X/posts - Svi postovi jednog korisnika •GET /users/X/posts/Y - Jedan post jednog korisnika (ili bolje

GET /posts/Y - Jedan post)

Sub-resources:

DELETE resources


•DELETE /posts/X - Briše jedan post •DELETE /posts/X,Y,Z - Briše više postova •DELETE /posts - Briše sve postove - opasan endpoint! •DELETE /posts/X/images - Briše sve slike vezane za jedan post

POST vs PUT War


Koristite POST ako ne znate tačnu lokaciju resursa.

Primer:

POST /articles HTTP/1.1 HTTP/1.1 201 Created Location: /articles/63636

POST vs PUT War


Sad kad znate tačnu lokaciju resursa koristite PUT da ga ažurirate.

Primer:

PUT /article/63636 HTTP/1.1

Idempotencija i sigurnost HTTP metoda


Sigurnim HTTP metodamase smatraju one koje ne menjaju resurs.

Idempotentnim HTTP metodama se smatraju one koje mogu da se pozivaju više puta,bez da se rezultat, ali ne obavezno i resurs, nakon poziva promeni. Na primer, možemo pokušati sa postavljanjem slike jednom ili više puta, u slučaju da postoji problem sa konekcijom.

Idempotencija i sigurnost HTTP metoda


POST vs PUT War


Zaključak:

PUT je idempotentna nesigurna metoda,dok POST nije ni jedno ni drugo.

Endpoints Plural or Singular?

RESTful API-centric UniverseENDPOINTS - PLURAL OR SINGULAR?

Primer: GET /user/1 vraća jednom korisnika sa ID-em 1

Šta vraća GET /user - jednog ili više korisnika? Nejasno.



Možda da probamo: GET /user/1 odnosno GET /users

…ali šta je sa nepravilnim množinama engleskog jezika:GET /person/1 ili GET /people Zbunjujuće?



GET /users/1 GET /users GET /users/1/images

Množina kao rešenje:

"1 Controller per Resource"

RESTful API-centric UniverseKONTROLERI

UsersController ImagesController PostsController

JSON vs XML Output

Prednosti JSONa nad XMLom:

RESTful API-centric UniverseJSON VS XML OUTPUT

• manja veličina fajla • XML ima problem sa čuvanjem tipa podataka

Svi moderni API servisi podržavaju JSON output.

RESTful API-centric UniverseJSON VS XML OUTPUT

JSON:

{ "user": { "id": 1, "name": "Tihomir", "active": true, "image": null, "empty_string": "" }}

<users> <user> <id>1</id> <name>Tihomir</name> <active>1</active> <image /> <empty_string /> </user></users>

<users> <user id="1" active="1"> <name>Tihomir</name> <image /> <empty_string /> </user></users>

XML: XML sa atributima:

Primeri prikaza tipa podataka:

JSON API

jsonapi.orgpreporuka formata

RESTful API-centric UniverseJSON API

Primer (tražimo jedan podatak):

{ "posts": [{ "id": "1", "title": "Rails is Omakase" }]}

Prednosti: Nedostaci:

•Konzistentnost • Pojedini frameworci se ne snalaze sa ovakvim outputom

•Zbunjujuće: Tražio sam jedan podatak a dobio kolekciju

http://jsonapi.org

twitter.com APIRESTful API-centric UniverseJSON API


{ "name": "Tihomir Opacic", "id": "500501255"}


•Minimalizam •Većina frameworka se snalazi

sa ovakvim outputom

• Nedostaje prostor za paginaciju i ostale meta podatke

{ "name": "John Galt", "id": "1001"},{ "name": "Jack Harper", "id": "1002"}

Primer (tražimo kolekciju):

facebook.com APIRESTful API-centric UniverseJSON API


{ "name": "Tihomir Opacic", "id": "500501255"}


•Minimalizam •Većina frameworka se snalazi

sa ovakvim outputom •Postoji prostor za paginaciju i

ostale meta podatke

• Nedostaje prostor za meta podatke u primeru zahtevanja jednog podatka

{ "data": [ { "name": "John Galt", "id": "1001" }, { "name": "Jack Harper", "id": "1002" } ]}


Namespace Everything



{ "data": { "name": "Tihomir Opacic", "id": "500501255" }}






{ "data": { "name": "Tihomir Opacic", "id": "500501255" }}





Primer (tražimo podatak o jednom korisniku, sa slikama):

{ "data": { "name": "Tihomir" "id": 1234, "photos": { "data": [ { "id": 111 "url": "http://media.example.com/profile_large.jpg" } ] } }}

HTTP Status Codes

RESTful API-centric UniverseSTATUS CODES

1xx is all about information (not used at all in APIs) 2xx is all about success 3xx is all about redirection 4xx is all about client errors 5xx is all about service errors

HTTP Status Codes

RESTful API-centric UniverseSTATUS CODES

Primer:(https://leanpub.com/build-apis-you-wont-hate)

200 - Generic everything is OK 201 - Created something OK 202 - Accepted but is being processed async (encoding a video, resizing image, etc) 400 - Bad Request (should really be for invalid syntax, but some folks use for validation) 401 - Unauthorized (no current user and there should be) 403 - The current user is forbidden from accessing this data 404 - That URL is not a valid route, or the item resource does not exist 410 - Data has been deleted, deactivated, suspended, etc 405 - Method Not Allowed (your framework will probably do this for you) 500 - Something unexpected happened and it is the APIs fault 503 - API is not here right now, please try again later

https://leanpub.com/build-apis-you-wont-hate

RESTful API-centric Universe

Primer API greške:

{ "error": { "type": "NotLoggedInException", "message": "User session has expired at unix time 1385221367." }}

STATUS CODES

Typecasting"When building an API it is common for people to just grab stuff from the database and pass it to json_encode().”

Laravel: User::find(1)->toJson();

RESTful API-centric UniverseTYPECASTING WITH FRACTAL

Često će baza podataka vratiti sve podatke tipa string,pa ćemo verovatno imati:

{ "user": { "id": "1", "name": "Tihomir", "active": "1" }}

{ "user": { "id": 1, "name": "Tihomir", "active": true }}UM

ESTO

Fractal

RESTful API-centric UniverseTYPECASTING WITH FRACTAL

https://github.com/thephpleague/fractal

"Fractal provides a presentation and transformation layer for complex data output, the like found in RESTful APIs, and works really well with JSON.”

Data RelationshipOverview of Methods

Sub-Resources

RESTful API-centric UniverseDATA RELATIONSHIPS

Za svaki podresurs kreirati endpoint:

GET /users/X/posts

Nedostatak: Za svaki resurs potrebno je napraviti dodatni API pozivda bi dobili podresurs (1 + n).

Compound Documents (Side-Loading)


Nedostatak: Ovakav API output često ostavlja previše posla programerima klijentske strane aplikacije.

{ "users": [ { "id": 1, "name": "Tihomir Opacic" }, { "id": 2, "name": "John Galt" } ],

"posts": [ { "id": 1, "author_id": 1, "title": "Some Title", }, { "id": 2, "author_id": 1, "title": "Some Title", }, { "id": 3, "author_id": 2, "title": "Some Title", } ]}

Embedded Documents (Nested-Loading)


GET /users?embedd=photos,posts{ "data": { "name": "Tihomir" "id": 1234, "photos": { "data": [ { "id": 111 "url": “http://bit.ly/1.jpg" } ] }

"posts": { "data": [ { "id": 111 "title": "Post Title" } ] } }}

Generalno najfunkcionalniji od svih načina prikaza relacionih podataka.

Embedded Documents with Fractal


https://github.com/thephpleague/fractal

Fractal je koristan i za kreiranje Nested-Loading API prikaza!

RESTful API Testing

Cucumber

RESTful API-centric UniverseRESTFUL API TESTING

http://cukes.info/

Behat (BDD for PHP)http://behat.org/

Both use Gherkin(Domain-Specific Language)

http://docs.behat.org/guides/1.gherkin.html

Gherkin

RESTful API-centric UniverseRESTFUL API TESTING

Primer API Outputa:

{ "user": { "id": 1, "name": "Tihomir" }}

Feature:Places

Scenario:Finding a specific user When I request "GET /users/1" Then I get a "200" response And scope into the "data" property And the properties exist: """ id name """ And the id property is an integer And reset scope

Primer Gherkin testa:

RESTful API Debugging

POSTMAN

RESTful API-centric UniverseDEBUGGING

http://www.getpostman.com/

A powerful HTTP client to test web services. (A Chrome browser plugin)


Clockwork


https://github.com/itsgoingd/clockwork-chrome

"Clockwork is a Chrome extension for PHP development, extending Developer Tools with a new panel providing all kinds of information useful for debugging and profiling your PHP scripts."


RESTful API Authentication

Standardna web aplikacija koristi sesije.

RESTful API-centric UniverseAUTHENTICATION

Restful API ne koristi sesije.

Basic Authentication


Najlakši ali i najnesigurniji sistem za autentifikacije.

echo base64_decode(‘dGlob21pcjoxMjMxMjM=‘); // tihomir:123123

Authorization: Basic dGlob21pcjoxMjMxMjM=

Header:

PHP:

Digest Authentication


Slično Basic autentifikaciji, nešto bezbedniji sistem jer koristi MD5 enkripciju, ali i dalje nebezbedan.

MD5... 4... 3... 2... 1... HACKED!

OAuth 1.0a Authentication


Sa pojavom OAuth 2 prestao da bude popularan izbor.

OAuth 2.0 Authentication


Da bi koristili OAuth 2.0 trebaće vam OAuth 2.0 Serverhttps://github.com/thephpleague/oauth2-server/

Proučite specifikacije OAuth 2.0 protokola:http://tools.ietf.org/html/draft-ietf-oauth-v2-23

Primer jednostavnog i sigurnog poziva:GET https://graph.facebook.com/me?access_token=DFGJKHDFGHDIFHG

RESTful API Pagination

RESTful API-centric UniversePAGINATION

{ "data": [ ... ], "pagination": { "total": 1000, "count": 12, "per_page": 12, "current_page": 1, "total_pages": 84, "next_url": "https://api.example.com/users?page=2&number=12" }}

Problem #1: SELECT count(*);Problem #2: Ako se između dva HTTP zahteva u bazu dodaju novi podaci, isti podaci će biti prikazani dva puta.

RESTful API-centric UniversePAGINATION

{ "data": [ ... ], "pagination": { "cursors": { "after": 12, "next_url": "https://api.example.com/users?cursor=12&number=12" } }}

Offsets and Cursors

“Daj mi 12 podataka od podatka broj 12.”

RESTful API Dokumentacija

Swagger

RESTful API-centric UniverseDOKUMENTACIJA

https://helloreverb.com/developers/swagger

"Swagger™ is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.”


API Blueprint


http://apiary.io/blueprint

"API Blueprint is a documentation-oriented API description language.”

We’re hiring!

www.orangehilldev.com

[email protected] +381.64.167.7367

Djordja Stanojevica 9b,11000 Belgrade, Serbia

http://www.orangehilldev.com

mailto:[email protected]