RESTful API-centric Universe

RESTful API-centric Universe
TIHOMIR OPAČIĆ
Orange Hill, Beograd

PHIL STURGEON*
Building APIs
You Won’t Hate
https://leanpub.com/build-apis-you-wont-hate
*founder of PyroCMS, Software Developer at Kapture

GDE SE KORISTI RESTful API?
Web Facing
mobile
aplikacije
iOS, Android…

Javscript
MVVM
Frameworks Angular JS,
Ember, Backbone…

Google Glass
API
https://developers.google.com/glass/v1/reference/

Tesla Model S
REST API
http://docs.timdorr.apiary.io/

1 2 3 4 5 6
Code on
Demand
ŠTA JE TO REST?
REpresentational State Transfer
Layered
System
Arhitekturni model definisan u šest principa:
Client-
Stateless Cacheable Server Uniform
Interface

ŠTA JE TO REST?
Uniformni interfejs
1 Uniform Interface
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.

ŠTA JE TO REST?
Nepostojanje stanja
2 Stateless
Nepostojanje stanja je osnovna odlika REST
arhitekture.
Svaki zahtev i odgovor servera na zahtev su
jedinstvene nezavisne transakcije.

ŠTA JE TO REST?
Mogućnost keširanja
3 Cacheable
Klijent je slobodan da kešira podatke koje je
primio kao odgovor servera, ukoliko server
explicitno označi podatke da se mogu keširati.

ŠTA JE TO REST?
Klijent-Server
4 Client-Server
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.

ŠTA JE TO REST?
Slojeviti sistem
5 Layered System
Klijent nema načina da zna da li je povezan
direktno na krajnji server. Ovaj princip omogućava
skalabilnost servisa (load balancing, shared
cache).

ŠTA JE TO REST?
Kod na zahtev
6 Code on Demand
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.

REST MODEL U WEB SERVISIMA
Servis koji se kreće u
granicama REST principa
naziva se RESTful servisom.
http://en.wikipedia.org/wiki/Representational_state_transfer

REST MODEL U WEB SERVISIMA
Karakteristike
RESTful API servisa:
• 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

RESTful 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 bi
razvijao ovakve API metode:
• GET
• POST
• PUT
• DELETE
• getUsers()
• getNewUsersSince(SinceDate)
• saveOrder(CID, PurchaseID)

BAZA PODATAKA
1 Dizajniranje baze podataka
2 Popunjavanje baze podacima
(Seeding)
Zašto je seeding bitan?

SEEDING
Seeding
“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 potrebnog
da se baza podataka popuni test podacima.

SEEDING
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."

SEEDING
Faker
Primer:
<?
$faker = FakerFactory::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'
]);
}

SEEDING
Da li koristiti Random
podatke za svaki
Seeding proces?
Da li se Acceptance testovi
oslanjaju na nepromenljive podatke u bazi?

SEEDING
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."

SEEDING
iSeed
Primeri:
$ php artisan iseed users
<?
Iseed::generateSeed('users’);
Iseed::generateSeed(‘photos’);
Iseed::generateSeed(‘categories');

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

ENDPOINTS
Endpoints Planning
Users
- Create
- Read
- Update
- Delete
- List (active, suspended) - Image
Posts
- Create
- Read
- Update
- Delete
- List (approved, disapproved)

Naming Convention
Best Practices

NAMING CONVENTIONS
GET resources
•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
Sub-resources:
•GET /users/X/posts - Svi postovi jednog korisnika •GET /users/X/posts/Y - Jedan post jednog korisnika (ili bolje
GET /posts/Y - Jedan post)

NAMING CONVENTIONS
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

NAMING CONVENTIONS
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

NAMING CONVENTIONS
POST vs PUT War
Sad kad znate tačnu lokaciju resursa
koristite PUT da ga ažurirate.
Primer:
PUT /article/63636 HTTP/1.1

NAMING CONVENTIONS
Idempotencija i sigurnost
HTTP metoda
Sigurnim HTTP metodama
se 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.

NAMING CONVENTIONS
Idempotencija i sigurnost
HTTP metoda

NAMING CONVENTIONS
POST vs PUT War
Zaključak:
PUT je idempotentna nesigurna metoda,
dok POST nije ni jedno ni drugo.

ENDPOINTS - PLURAL OR SINGULAR?
Endpoints
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.

Endpoints
Plural or Singular?
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?

Endpoints
Plural or Singular?
GET /users/1
GET /users
GET /users/1/images
Množina kao rešenje:

KONTROLERI
"1 Controller per Resource"
UsersController
ImagesController
PostsController

JSON VS XML OUTPUT
Prednosti JSONa nad XMLom:
• manja veličina fajla • XML ima problem sa čuvanjem tipa podataka
Svi moderni API servisi podržavaju JSON output.

JSON VS XML OUTPUT
JSON:
{
"user": {
"id": 1,
"name": "Tihomir",
"active": true,
"image": null,
"empty_string": ""
}
}
XML: XML sa atributima:
<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>
Primeri prikaza tipa podataka:

jsonapi.org
preporuka formata
JSON 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

JSON API
RESTful API-centric Universe twitter.com API
{
"name": "Tihomir Opacic",
"id": "500501255"
}
Primer (tražimo kolekciju):
•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"
}

RESTful API-centric Universe facebook.com API
JSON API
{
"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": [
{
"id": "1001"
},
{
"id": "1002"
}
]
}

Namespace
Everything
JSON API
{
"data": {
"id": "500501255"
}
}
{
"data": [
{
"id": "1001"
},
{
"id": "1002"
}
]
}

Namespace
Everything
JSON API
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"
}
]
}
}
}

STATUS CODES
HTTP Status 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

STATUS 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

STATUS CODES
Primer API greške:
{
"error": {
"type": "NotLoggedInException",
"message": "User session has expired at unix time 1385221367."
}
}

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();

TYPECASTING 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
}
UMESTO
}

TYPECASTING WITH FRACTAL
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 Relationship
Overview of Methods

DATA RELATIONSHIPS
Sub-Resources
Za svaki podresurs kreirati endpoint:
GET /users/X/posts
Nedostatak:
Za svaki resurs potrebno je napraviti dodatni API poziv
da bi dobili podresurs (1 + n).

DATA RELATIONSHIPS
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,
},
{
"id": 3,
"author_id": 2,
}
]
}

DATA RELATIONSHIPS
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.

DATA RELATIONSHIPS
Embedded Documents
with Fractal
https://github.com/thephpleague/fractal
Fractal je koristan i za kreiranje Nested-Loading API prikaza!

RESTFUL API TESTING
Cucumber
http://cukes.info/
Behat (BDD for PHP)
http://behat.org/
Both use Gherkin
(Domain-Specific Language)
http://docs.behat.org/guides/1.gherkin.html

RESTFUL API TESTING
Gherkin
Primer API Outputa:
{
"user": {
"id": 1,
"name": "Tihomir"
}
}
Primer Gherkin testa:
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

DEBUGGING
POSTMAN
http://www.getpostman.com/
A powerful HTTP client to test web services.
(A Chrome browser plugin)

DEBUGGING

DEBUGGING
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."

AUTHENTICATION
Standardna web aplikacija
koristi sesije.
Restful API ne koristi sesije.

AUTHENTICATION
Basic Authentication
Najlakši ali i najnesigurniji sistem za autentifikacije.
Header:
Authorization: Basic dGlob21pcjoxMjMxMjM=
PHP:
echo base64_decode(‘dGlob21pcjoxMjMxMjM=‘); // tihomir:123123

AUTHENTICATION
Digest Authentication
Slično Basic autentifikaciji, nešto bezbedniji sistem jer koristi
MD5 enkripciju, ali i dalje nebezbedan.
MD5... 4... 3... 2... 1... HACKED!

AUTHENTICATION
OAuth 1.0a Authentication
Sa pojavom OAuth 2 prestao da bude popularan izbor.

AUTHENTICATION
OAuth 2.0 Authentication
Da bi koristili OAuth 2.0 trebaće vam OAuth 2.0 Server
https://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

PAGINATION
{
"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.

PAGINATION
Offsets and Cursors
{
"data": [
...
],
"pagination": {
"cursors": {
"after": 12,
"next_url": "https://api.example.com/users?cursor=12&number=12"
}
}
}
“Daj mi 12 podataka od podatka broj 12.”

DOKUMENTACIJA
Swagger
https://helloreverb.com/developers/swagger
"Swagger™ is a specification and complete framework
implementation for describing, producing, consuming, and
visualizing RESTful web services.”

DOKUMENTACIJA

DOKUMENTACIJA
API Blueprint
http://apiary.io/blueprint
"API Blueprint is a documentation-oriented API description
language.”

We’re hiring!
www.orangehilldev.com
tihomir.opacic@orangehilldev.com
+381.64.167.7367
Djordja Stanojevica 9b,
11000 Belgrade, Serbia

RESTful API-centric Universe

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (20)

Similaire à RESTful API-centric Universe

Similaire à RESTful API-centric Universe (20)

Dernier

Dernier (20)

RESTful API-centric Universe