web services, rest · hydra: hypermedia-driven web apis (1) hydra is an e ort to combine linked...

Web Services REST

Miroslav Blasko

miroslavblaskofelcvutcz

November 1 2017

Miroslav Blasko (miroslavblaskofelcvutcz) Web Services REST November 1 2017 1 29

Contents

1 Web services

2 RESTful web services

3 Linked data


Web services

Web services


Web services

What is a web service

A Web service is a software system designed to supportinteroperable machine-to-machine interaction over a network

mdash W3C Web Services Glossary

We can identify two major classes of Web services

REST-compliant Web services in which the primary purposeof the service is to manipulate XML representations of Webresources using a uniform set of rdquostatelessrdquo operations andarbitrary Web services in which the service may expose anarbitrary set of operations

mdash W3C Web Services Architecture (2004)


Web services

Comparison of API protocols and styles (2008-2010)

Figure Distribution of different API protocols and styles based onProgrammableWebrsquos directory of more than 2000 web APIs Sourcehttproyalpingdomcom20101015rest-in-peace-soap


Web services

Interest over time for major web service APIs

Figure Interest over time for REST API versus SOAP API based on GoogleInsights for Search Source httpswwwgooglecomtrends


RESTful web services




Basic terms

Uniform Resource Identifier (URI) is a string of characters used toidentify a resource (eghttpwwwfelcvutczczeducation)

The Hypertext Transfer Protocol (HTTP) is an applicationprotocol for distributed collaborative hypermedia informationsystems It is foundation of data communication for the World WideWeb

initiated by Tim Berners-Lee at CERN in 1989

Representational State Transfer (REST) is architectural style fordistributed hypermedia systems

defined in 2000 by Roy Fielding in his doctoral dissertation



HTTP protocol basics

HTTP is a client-serverapplication-level protocol

typically runs over a TCPIPconnection

Example of HTTP Request Message (left part) and HTTP Response Message(right part) The request accesses URLhttpwwwtest101comdoctesthtmlbookId=12345ampauthor=Tan+Ah+Teck In addition to the description therequest line can be devided into 3 parts request method (ie ldquoGETrdquo) request URI (ie ldquodoctesthtmlrdquo) and HTTP protocolversion (ie ldquoHTTP11rdquo) Request message body consist of 2 request parameters ldquobookIdrdquo and ldquoauthorrdquo SourcehttpswwwntuedusghomeehchuaprogrammingwebprogrammingHTTP_Basicshtml



Understanding REST

REST is architectural style not standard

It was designed for distributed systems to address architecturalproperties such as performance scalability simplicity modifiabilityvisibility portability and reliability

REST architectural style is defined by 6 principlesarchitecturalconstraints (eg client-server stateless)

SystemAPI that conforms to the constraints of REST can be calledRESTful



REST principles

client-server

uniform interface

resource-basedmanipulation of resource through representationself-descriptive messageshypermedia as the engine of application state

stateless interactions

cacheable

layered system

code on demand (optional)



Building RESTful API

can be build on top of existing web technologies

reuseing semantics of HTTP 11 methods

safe and idempotent methodstypicaly called HTTP verbs in context of servicesresource oriented correspond to CRUD operationssatisfies uniform interface constraint

HTTP Headers to describe requests amp responses



HTTP verbs ndash GET

requests a representation of the specified resource

should be safe and idempotent

can have side-effects but not expected

can be conditional or partial (If-Modified-Since Range)

Example ndash retrieve user with id 123

GET users123



HTTP verbs ndash POST

requests to do something with the specified resource

does not have to be safe or idempotent

can be used for create and update

Example ndash create user

POST users ldquofirstNamerdquo ldquoKarelrdquo

ldquolastNamerdquo ldquoNovakrdquo



HTTP verbs ndash PUT

requests to store specified entity at a specified URI

should be idempotent but not safe


Example ndash update user with id 123

PUT users123 ldquofirstNamerdquo ldquoKarelrdquo




HTTP verbs ndash DELETE

deletes specified resource


deletition does not have to be immediate

Example ndash delete user with id 123

DELETE users123



HTTP Status Codes

classifies the result of the HTTP request

main categories of status codes with most common specific codes are

1xx - informational2xx - success3xx - redirection4xx - client error5xx - server error



Common HTTP status codes indicating error

4xx - client error

400 Bad Request ndash malformed syntax retry with modified request401 Unauthorized ndash authentication is required403 Forbidden ndash server has understood but refuses request404 Not Found ndash server cannot find a resource by specified URI409 Conflict ndash resource conflicts with client request

5xx - server error

500 Internal Server Error ndash server encountered an unexpectedcondition which prevented it from fulfilling the request



Other common HTTP status codes

200 OK ndash request has succeeded

201 Created ndash returns a Location header for new resource

204 No Content ndash server fulfilled request but has nothing to return

304 Not Modified ndash accessed document was not modified thuscache can be used



Recommended interaction of HTTP methods wrt URIs

HTTP Verb CRUD Collection (eg users) Specific Item (eg usersid)POST Create 201 Createdlowast1 404 Not Found409 Conflictlowast3

GET Read 200 OK list of users 200 OK single user404 Not Foundlowast4

PUT UpdateReplace 404 Not Foundlowast2 200 OK204 No Content404 Not Foundlowast4

PATCH UpdateModify 404 Not Foundlowast2 200 OK204 No Content404 Not Foundlowast4

DELETE Delete 404 Not Foundlowast2 200 OK404 Not Foundlowast4

Table Recommended return values of HTTP methods in combination with theresource URIs (1) ndash returns Location header with link to usersid containingnew ID (2) ndash unless you want to updatereplacemodifydelete wholecollection (3) ndash if resource already exists (4) ndash if ID not found or invalid



Naming conventions

resources should have name as nouns not as verbs or actions

plural if possible to apply

URI should follow a predicatable (ie consistent usage) andhierarchical structure (based on structure-relationships of data)

Correct usages

POST customers12345orders121lineitemsGET customers12345orders121lineitems3GET|PUT|DELETE customers12345configuration

Anti-patterns

GET servicesop=update customerampid=12345ampformat=jsonPUT customers12345update



The Richardson Maturity Modelprovides a way to evaluate compliance of API to REST constraints

Figure A model (developed by Leonard Richardson) that breaks down theprincipal elements of a REST approach into three steps about resources httpverbs and hypermedia controls Source httpmartinfowlercomarticlesrichardsonMaturityModelhtml


Linked data

Linked data


Linked data

What is Linked data

Linked Data is a method of publishing structured data so that it canbe interlinked and queried

it builds upon standard Web technologies to share information in away that can be read automatically by computers

there is already a vast amount of data in Linked Data formatavailable on the Web (eg Linking Open Data cloud)

JSON-LD (JSON for Linking Data) a lightweight Linked Dataformat based on JSON


Linked data

Linked open cloud

Figure Linked Open Data cloud Each buble represent a dataset while edgesrepresent links across datasets There are about 1011 statements about resourceswithin all datasets of the cloud Source httplod-cloudnet


Linked data

Hydra Hypermedia-Driven Web APIs (1)

Hydra is an effort to combine Linked Data principles to publish dataand REST principles for web services

REST services are used with JSON-LD format instead of plain JSON


Linked data



GET user123

Response is in JSON-LD

ldquocontextrdquo ldquohttpschemaorgrdquoldquotyperdquo ldquoPersonrdquoldquoidrdquo ldquouser123rdquoldquogivenNamerdquo ldquoKarelrdquoldquofamilyNamerdquo ldquoNovakrdquo

Type of the resource (ie ldquohttpschemaorgPersonrdquo) as well asspecific properties (ie ldquohttpschemaorggivenNamerdquoldquohttpschemaorgfamilyNamerdquo) are dereferencable It is used todescribe semantics of the schema in human-readable as well asmachine-readable way


Linked data

The End

Thank You


Linked data

Resources

Fielding RT 2000 Architectural styles and the design ofnetwork-based software architectures (Doctoral dissertationUniversity of California Irvine)

Fowler M 2010 Richardson Maturity Model steps toward the gloryof REST Online at httpmartinfowlercomarticlesrichardsonMaturityModelhtml

Lanthaler M and Gutl C 2012 April On using JSON-LD to create evolvableRESTful services In Proceedings of the Third International Workshop on RESTfulDesign (pp 25-32) ACM

httpsspringiounderstandingREST

httpwwwrestapitutorialcom


Web services


Linked data

Contents

1 Web services

2 RESTful web services

3 Linked data


Web services

Web services


Web services








Web services




Web services








Basic terms














Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Web services

Web services


Web services








Web services




Web services








Basic terms














Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Web services








Web services




Web services








Basic terms














Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Web services




Web services








Basic terms














Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Web services








Basic terms














Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data





Basic terms














Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data








Understanding REST







REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data


REST principles

client-server

uniform interface



cacheable

layered system

















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data















GET users123


























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

























DELETE users123



HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data


HTTP Status Codes







4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data



4xx - client error


5xx - server error




















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data


















Naming conventions




Correct usages


Anti-patterns







Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data





Linked data

Linked data


Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Linked data

What is Linked data






Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Linked data

Linked open cloud



Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Linked data





Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Linked data



GET user123





Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Linked data

The End

Thank You


Linked data

Resources







Web services


Linked data

Linked data

Resources







Web services


Linked data

web services, rest · hydra: hypermedia-driven web apis (1) hydra is an e ort to combine linked...

Documents