Professional Documents
Culture Documents
1. REST vs SOAP
RESTful services are services that follow a REST architectural style, as opposed to
SOAP.
- REST -> REpresentational State Transfer – One-way, stateless message passing.
- SOAP -> Simple Object Access Protocol – One-way, stateless message passing.
SOAP:
Action based
We use only verbs -> actions we can call getUserData
An envelope, which defines the message structure[1] and how to process it
A set of encoding rules for expressing instances of application-defined datatypes
A convention for representing procedure calls and responses
- 3 constraints or characteristics:
o Extensibility -> e.g. Security and WS-Addressing extensions
o Neutrality -> It can operate over any protocol: HTTP, SMTP, TCP, UDP…
o independence -> It allows for any programming model
REST:
It was part of Roy Fieldings final doctoral dissertation
(https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
- It is resource-based, not action based -> In a RESTful Api we talk about things
or resources.
- We use nouns in form of URIs: a person resource (URI), an address resource
(URI), and http verbs for actions or services on those nouns/resources: GET,
POST, PUT, DELETE.
- Multiple URIs can point to the same resource.
- There can be different data representations from the same resource, it is what
is transferred via the clients. It contains enough information to manipulate the
resource (typicaly they use json or xml formats).
1
2. REST six constraints
o Uniform interface
o Stateless(ness)
The service should contain no client state, each message or request should
contain enough information so that the server can know what to do, which
means, if there is a state, it should be at the client side, not at the server side.
- Self descriptive messages
- Any session state is held on the client
Note: OAuth2 is statefull but built in a REST fashion, so there are cases in which
you have to store the state in the server side. But, in general, we should avoid
that. See https://en.wikipedia.org/wiki/OAuth.
o Client-server
That means we are dealing with a disconnected system. This means that it is
possible that we cannot connect or reconnect to our database or to our assets, or
to our services, and we need to handle those cases.
So it helps separating concerns in what is user interface and what are services.
They will communicate via the Uniform interface (nouns and verbs).
o Cacheable
Server responses, anything that comes back from the service
- can be cacheable by the client (implicit caching), or
- the server specifies a maxAge header (explicit caching), or
- client and service negotiate how long the response can be cached
(negotiated caching).
o Layered system
- Relates to cacheability and client-serve
- A RESTful could have multiple layers of software inbetween, so we don’t know
who we are deling with in the server.
- So if a get a representation, I don’t know if it is cached or it comes from the
database, I just get a representation of the resource I need.
2
o Code on Demand (optional)
- From a RESTful server, logic could be transferred as the representation to the
client. E.g. Java applets, executable JavaScript snippets, could be delivered via
RESTful apis.
If you comply with all these first 5 constraints, if you are RESTful compliant, otherwise
you just use the REST interface. If we are RESTful (completely REST), we get the
following benefits:
- Scalability
- Simplicity
- Modifiability
- Visibility
- Portability
- Reliability
3
3. Best practices when defining RESTful URIs
Producing a great API is 80% art and 20% science. Creating a URL hierarchy
representing sensible resources is the art part. Having sensible resource names (which
are just URL paths, such as /customers/12345/orders) improves the clarity of what a
given request does.
Here are some quick-hit rules for URL path (resource name) design:
Use the HTTP methods to specify the verb portion of the request.
Use identifiers in your URLs instead of in the query-string. Using URL query-
string parameters is fantastic for filtering, but not for resource names.
Good: /users/12345
Poor: /api?type=user&id=23
This way, /customers will manage a list of customers and /customers/{id} will
manage a specific customer.
4
4. Http verbs
- GET (Readonly)
Read a specific resource (by an identifier) or a collection of resources.
- PUT
Update a specific resource (by an identifier) or a collection of resources. Can also
be used to create a specific resource if the resource identifier is known before-
hand.
- DELETE
Remove/delete a specific resource by an identifier.
- POST
Create a new resource. Also a catch-all verb for operations that don't fit into the
other categories.
Suggested usages for the "Top 10" HTTP Response Status Codes are as follows:
2XX (Success)
- 200 OK – GET, PUT, POST, DELETE
General success status code. This is the most common code. Used to indicate
success.
- 201 CREATED – after PUT or POST (never on GET, DELETE)
Successful creation occurred (via either PUT or POST). Set the Location header to
contain a link to the newly-created resource (on POST). Response body content
may or may not be present.
- 204 NO CONTENT – PUT, DELETE
Indicates success but nothing is in the response body, often used for DELETE and
PUT operations.
5
4XX (Client error)
Errors that the client can be able to solve by their end by changing the values of their
request (headers, body, query parameters, …).
https://www.restapitutorial.com/httpstatuscodes.html
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
6
HTTP CRUD Specific Item Entire Collection
Verb operations /customers/{id} /customers
GET Read 200 (OK) Single customer. 200 (OK), list of customers. Use
pagination, sorting and filtering to
404 (Not Found) If ID not found or navigate big lists.
invalid.