Upload
paul-boocock
View
171
Download
0
Embed Size (px)
Citation preview
Writing RESTful Web ServicesCodeweavers Development Series
Introduction● What is a RESTful Web Service?● How should we create one?● Some Tips, Tricks and Guidelines● Introduction to HATEOAS, HAL & JSON-LD● REST vs RPC
2
RESTRepresentationalStateTransfer
3
Roy Thomas Fielding’s PhD Thesis- Architectural Styles and Design of
Network-based Software Architectures (2000)
HTTPDeveloped alongside HTTP 1.1
REST doesn’t define a standard protocol but HTTP is most commonly used
4
RESTfulREST isn’t a standard but a style for creating systems
Systems that follow observe REST constraints are said to be RESTful
5
ArchitecturePerformance
ScalabilitySimplicity
ModifiabilityVisibility
PortabilityReliability
6
Architectural ConstraintsClient-Server
(Representations & Messages)
StatelessCacheable
LayeredUniform Interface
7
RepresentationsResources
How to provide access to resources{ "ID": "1", "FirstName": "Paul", "LastName": "Boocock", "Email": "[email protected]"}
Could also be XML
8
RepresentationsResources can contain other resourcesClient and Server can comprehendCan completely represent the resource
Break big resources down into smaller onesRepresentations can link to each other
9
CacheableStore the results and on the next request serve the same responseCaching can be controlled with HTTP Headers
Date, Last Modified, Cache-Control, Expires, Age
Be careful you don’t start serving stale results10
StatelessDo not maintain state for any client
HTTP is stateless by designBad Design:
https://OrderService/Orders/1https://OrderService/Orders/NextOrder
11
LinksSay hello to HATEOAS!
Hypermedia as the engine of application stateThese can be generated dynamicallyAllow clients to transition through the supported actions by the server
12
Uniform InterfaceRESTful systems should have a Uniform Interface
HTTP v1.1 provides thisURIs to identify resourcesHTTP Verbs to manipulateHTTP Headers to help parse (MIME Types)Hyperlinks to navigate
13
RESTful Web ServicesClients and Servers have to talk to each other
Commonly use HTTP
Client sends a requestServer replies with a response
14
HTTP RequestsVerbs
UriHTTP Version
HeadersBody
15
HTTP ResponseHTTP Version
Response CodeHeaders
Body
16
Addressing ResourcesEach resources should have at least one URIA typical convention:
Protocol://ServiceName/ResourceType/ResourceID
The HTTP Verb decides the operation performed
17
Addressing ResourcesUse plural nouns for naming resourcesAvoid spacesBe consistent!Take your time, a good URI will stick aroundAvoid verbs for resource names
BAD: https://OrderService/RetrieveOrder/118
Idempotent or Not?A service that can be called multiple times without different outcomes is Idempotent.
Safe methods are ones which do not modify a resource.
19
VERBS
20
Method Operation performed on server Safe Idempotent
GET Read a resource. Yes Yes
PUT Insert a new resource or update if the resource exists. No Yes
POST Insert a new resource. Also can be used to update an existing resource.
No No
PATCH Update a resource with a partial update or instruction No No
DELETE Delete a resource. No Yes
OPTIONS List the allowed operations on a resource. Yes Yes
HEAD Return only the response headers and no response body. Yes Yes
PUT vs POST vs PATCH
21
PUT Insert a new resource or update if the resource exists. No Yes
POST Insert a new resource. Also can be used to update an existing resource.
No No
PATCH Update a resource with a partial update or instruction No No
Status CodesHTTP Responses contain status codes
These can be used to indicate success or failures of the request
2xx for Success4xx for Bad Request (You messed up)5xx for Server Error (We messed up)
22
Status CodesDon’t get carried away with Status Codes
Keeping usage of them simple is probably a good idea
Imagine having to handle every status code…Some nice ones though, like a 201 for Post
23
Handling ErrorsDon’t just use Status Codes for errors
400 Bad Request, 404 Not Found500 Internal Server Error
You should have a Errors array on the top level of your response
Code, Title, Message, Links, Source24
VersioningAPIs should be versioned
New version should be created on a breaking change
25
Breaking ChangesWhat is a breaking change?Depends!
Usually when something needs removing from the response or a new required field is added to the request Could be really strict! Any change...
26
LinksYou should be able to navigate a RESTful service just like a webpage
Should contain links to other relations
Some standards are starting to emerge...
27
HALHypertext Application Language
http://stateless.co/hal_specification.html
A number of NUGET Packages:https://www.nuget.org/packages/WebApi.Hal/https://www.nuget.org/packages/HoneyBear.HalClient/
28
JSON-LDA Linked Data format for JSON
http://json-ld.org/
Popular NUGET Package:https://www.nuget.org/packages/json-ld.net/
29
RPCRemote Procedure Call
Also uses HTTP ProtocolGET or POST an operation not a resourceOperations manipulate dataNo rules! Good to be consistent though.
30
REST vs RPCURIs represent:
REST = NounsRPC = Verbs
Similar in many waysREST is more predictable
31
REST vs RPC ExamplesRPC Options:
GET (or POST) /deleteItem?itemId=456GET (or POST) /removeIt?itemId=456GET (or POST) /trash?itemId=456
REST Option:DELETE /items/456
32
Other Stuff...CachingAuthorization Headers
ASP.Net Web Api 2...
33
ConclusionsThings don’t have to be RESTful to be right
Design consistent and reliable APIs
Don’t start Bikeshedding... 34
ConclusionsMake an educated decision on the right style for the task at hand
RESTful Services probably best for CRUD resourcesREST is good for public services as it is predictableDealing with Processes or Operations then a RPC style service might be betterRPC Services are arguably easier to designMaybe fewer calls with RPC Services?
35
Useful LinksJSON API - http://jsonapi.org/JSON-LD - http://json-ld.org/MS API Guidelines - https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.mdHTTP v1.1 - http://www.ietf.org/rfc/rfc2616.txt
36