A RESTful Introduction will cover the basics of what REST means and takes advantage of. We will talk about status codes, verbs and APIs in general. The presentation was held by Daniel Toader and Andrei Pirjoleanu from eMAG.

1. Join the discussion at
https://bit.ly/phpbucharest
#phpbucharest
Bucharest PHP
Meetup #10
Powered by
Agenda
18:45 - 19:00 Meet & Greet
19:00 - 20:00 A RESTful
Introduction
20:00 - 21:00 Networking
Ask questions using sli.do app
Event code: #phpmeetup

2. A RESTful Introduction

3. About us
XP:
● Programming & CS
○ 15 years
● Web & eCommerce
○ 10 years
● APIs & Services
○ 7+ years
● Large scale Enterprise
Software Architecture
○ 3+ years
Product Owner
@ eMAG
Andrei Pîrjoleanu
XP:
● Programming
○ 12+ years
● Trainer
○ 5 years
● eCommerce
○ 5 years
● APIs & Services
○ 9 years
Software Engineer
@ eMAG
Daniel Toader
3
/dantdr /danieltoader@dantdr/andreipirjoleanu /neneaX

4. Agenda
The RESTful road
What is REST? Principles Real World
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
4

5. Questions via sli.do
5
#phpmeetup

6. What is REST?
6
What, when, who, how

7. REpresentational State TransferRESTRESTfulRESTish
7

8. Who?
Roy Fielding defined REST in his 2000
PhD dissertation "Architectural Styles
and the Design of Network-based
Software Architectures" at UC Irvine.
Definition
What?
Representational state transfer (REST)
is a software architectural style that
defines a set of constraints to be used for
creating Web services.
When?
The REST architectural style has been
developed in parallel with HTTP 1.1 of
1996–1999, based on the existing
design of HTTP 1.0 of 1996.
8
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

9. Architectural Properties
Non-functional requirements
The constraints of the REST architectural style affect the following architectural properties:
● performance in component interactions, which can be the dominant factor in user-perceived performance and network
efficiency;
● scalability allowing the support of large numbers of components and interactions among components;
● simplicity of a uniform interface;
● modifiability of components to meet changing needs (even while the application is running);
● visibility of communication between components by service agents;
● portability of components by moving program code with the data;
● reliability in the resistance to failure at the system level in the presence of failures within components, connectors, or data.
9
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

10. Constraints
Web’s Architectural style
10
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
Client - Server1
Servers and clients may also be replaced and
developed independently, as long as the interface
between them is not altered.
Stateless2
No client context shall be stored on the server
between requests. The client is responsible for
managing the state of the application.
Cacheable3
Well-managed caching partially or completely
eliminates some client-server interactions, further
improving scalability and performance.
#phpmeetup

11. Constraints
Web’s Architectural style
11
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
Uniform Interfaces4
The uniform interface simplifies and decouples the
architecture, which enables each part to evolve
independently.
Layered System5
The client should only know the immediate layer it is
communicating with, and not be aware of any layers
behind it.
Code on demand6
A server can extend the functionality of a client on
runtime, by sending code to it that it should execute
(like PHP, Java Applets, or JavaScript).optional
#phpmeetup

12. RESTful principles
Helping applications to be simple, lightweight, and fast
12

13. Resources
What is a resource?
REST uses a resource identifier to identify the particular resource involved in an interaction between components.
The state of resource at any particular timestamp is known as resource representation.
The key abstraction of information
in REST is a resource.
”Roy Fielding’s dissertation
“
A resource can be anything that can be named:
● A document
● An image
● A temporal service
● A collection of other resources
● A non-virtual object (e.g.: a person)
13
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

14. Methods
What is a resource method?
A large number of people wrongly relate resource methods to HTTP GET/PUT/POST/DELETE methods.
The Uniform interface constraint should be applied and thus consistency should be followed, regardless of the chosen
implementation.
The clients and servers exchange representations of resources by using a standardized interface and protocol – typically HTTP.
Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML,
XML, plain text, PDF, JPEG, JSON, and others.
REST and HTTP are not the same.A resource method is used to perform the transition to
the next desired state of the resource representation.
14
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

15. HTTP design
Modeling & Best practices
Consistency is the key
● Archetypes can be used with consistent naming convention
1. Document (singular concept) - singular name
2. Collection (server managed) - plural name
3. Store (client-managed) - plural name
4. Controller - verb
➔ http://api.local/ad/
➔ http://api.local/management/
➔ http://api.local/ad/teams/{code}
➔ http://api.local/ad/users/{id}
➔ http://api.local/ad/teams/{code}/users/{id}
➔ http://api.local/ad/teams/{code}/users/{id}/resync
15
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

16. HTTP design
Modeling & Best practices
Consistency is the key
● HTTP Request methods can be used to manipulate resources
1. GET - Retrieve resource
2. POST - Create resource
3. PUT - Replace resource
4. PATCH - Apply delta (diff) between states (similar to SQL migrations)
5. DELETE - Remove resource
Uniform interface - HTTP POST can be used for updating a resource instead of HTTP PUT as long as it is consistent – it’s alright
and application interface will be RESTful.
Nevertheless, most well-designed APIs will use the verbs consistently and the same as any other API.
16
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

17. HTTP design
Modeling & Best practices
Consistency is the key
● HTTP Request methods can be used to manipulate resources
● Retrieve all
● Filter through all
● Retrieve single
● Add single
● Replace single
● Replace all
● Remove single
● Remove all
➔ GET http://api.local/ad/users
➔ GET http://api.local/ad/users?name=john
➔ GET http://api.local/ad/users/{id}
➔ POST http://api.local/ad/users
➔ PUT http://api.local/ad/users/{id}
➔ PUT http://api.local/ad/users
➔ DELETE http://api.local/ad/users/{id}
➔ DELETE http://api.local/ad/users
17
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

18. HTTP design
Modeling & Best practices
Consistency is the key
● HTTP Status codes can be used to inform clients
● 200 - OK
● 404 - Not Found
● 403 - Forbidden
● 201 - Created
● 202 - Accepted
● 405 - Method Not Allowed
● 500 - Internal Server Error
● 501 - Not Implemented
➔ GET http://api.local/ad/users
➔ GET http://api.local/ad/users?name=john
➔ GET http://api.local/ad/users/{id}
➔ POST http://api.local/ad/users
➔ PUT http://api.local/ad/users/{id}
➔ PUT http://api.local/ad/users
➔ DELETE http://api.local/ad/users/{id}
➔ DELETE http://api.local/ad/users
18
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

19. HTTP design
Modeling & Best practices
Consistency is the key
● HTTP Headers and Payloads
● Accept: application/json; - return JSON response
● Content-Type: application/json; - send JSON request
● Content-Type: application/xml; - send XML request
● Accept-version: v1 - use version v1 according to custom header
● Accept: application/vnd.example.v1 - use version v1 according to vendor specific media type header
● Authorization: Basic Zm9vOmJhcg== - use basic authorization header
● X-App-Auth: 123456abcdefgh - use token authorization with custom header
19
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

20. Maturity Levels
Leonard Richardson Maturity Model
Single URI & single verb
SOAP
Multiple URI-based resources & single verbs
Resources
Multiple URI-based resources and verbs
HTTP Verbs
Level 0 Level 1 Level 2 Level 3
Self-explanatory response
HATEOAS
20
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

21. Maturity Levels
Hypermedia as the Engine of Application State
HATEOAS is an architectural style that lets you use
hypermedia links in the response contents so that the client
can dynamically navigate.
References example - JSON REST API hypermedia links:
○ RFC 5988 (web linking)
■ Target URI
■ Link relation type
■ Attributes for target IRI
○ JSON Hypermedia API Language (HAL)
{
"data": [
{
"code": "j9x3p32gfv",
"name": "Edited List",
"created_at": "2019-09-23T22:51:57+00:00",
"updated_at": "2019-09-24T02:28:47+00:00"
}
],
"errors": [],
"page": {
"size": 1,
"total": 4,
"number": 3
},
"links": {
"self": "/todolist?page=3",
"first": "/todolist?page=1",
"last": "/todolist?page=4",
"next": "/todolist?page=4",
"prev": "/todolist?page=2"
}
}
21
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

22. Real world
Entering the matrix
22

23. ToDo List
Demo
Simple, RESTful API
example
23

24. APX
Application Programming eXperience
To deliver great APIs, design must be a first-order concern.
Optimizing for APX (API User Experience) should be a primary
concern in API development, as UX (User Experience) has
become a primary concern in UI development.
An optimal API design enables applications developers to easily
understand the purpose and functionality of the API so that they
can quickly become productive using it.
APX is to API as
UX is to UI
”
“
24
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

25. Tools
Resources
● Swagger - https://swagger.io/
● PHPStorm - https://www.jetbrains.com/help/phpstorm/testing-restful-web-services.html
● Postman - https://www.getpostman.com/
● RAML - https://raml.org/
● RESTful API - https://restfulapi.net/
25
W
hatisREST?
Principles
RealW
orld
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

26. Recap
The RESTful road
26
What is REST? Principles Real World
Definition
Properties
Constraints
Resources
Methods
HTTPdesign
APX
Tools
MaturityLevels
Demo
Q&A
#phpmeetup

27. 27
Q&A
27
#phpmeetup

28. Thank you!
28
Continue the discussion at
http://bit.ly/phpbucharest
#phpbucharest