REST and Hypermedia: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(67 intermediate revisions by the same user not shown)
Line 2: Line 2:


* https://www.programmableweb.com
* https://www.programmableweb.com
* https://learning.oreilly.com/videos/learning-path-resource-oriented/9781491960981


=Internal=
=Internal=
Line 8: Line 9:
* [[API Concepts]]
* [[API Concepts]]
* [[Amazon API Gateway Concepts]]
* [[Amazon API Gateway Concepts]]
* [[Spring REST Concepts]]
* [[Best Practices for Naming REST API URIs]]
=Overview=
HTTP APIs often use the Representational State Transfer (REST) architectural style, which is developed around the following principles:
* Organize the API around [[#Resource|resources]].
* Communicate actions using HTTP methods.
* Model response around standard HTTP status codes.


=API=
=API=


{{Internal|API Concepts|API Concepts}}
{{Internal|API Concepts|API Concepts}}
=<span id='URL'><span>Uniform Resource Locator (URL)=
{{Internal|URL|URL}}
=<span id='URI'><span>Uniform Resource Identifier (URI)=
{{Internal|URI|URI}}
=<span id='URN'></span>Uniform Resource Name (URN)=
{{Internal|URN|URN}}
=Endpoint=
A REST API endpoint is the interaction point where a specific URL is configured to receive web requests.
{{Internal|Best Practices for Naming REST API URIs#Overview|Best Practices for Naming REST API URIs}}


=Resource=
=Resource=


A resource is a logical entity that an application can access through a [[#Resource_Path|resource path]]. A resource is a top-level constituent of a [[API_Concepts#REST_and_Hypermedia_Concepts|REST API]].
A resource is a logical entity that an application can access through a [[#Resource_Path|resource path]]. A resource is a top-level constituent of a [[API_Concepts#REST_and_Hypermedia_Concepts|REST API]]. Resources are sometimes referred to as the '''nouns''' of the API. A resource has a number of [[#Method|methods]].
 
<font color=darkkhaki>TODO: receive data from client via path, Spring REST Concepts: [[Spring_REST_Concepts#Via_Path]]</font>


==Resource Path==
==Resource Path==
===<span id='Path_Parameter'></span><span id='Path_Variable'></span><span id=''Variable_Path_Part></span>Path Parameter, Path Variable, Variable Path Part===
{{Internal|HTTP_Request#Path_Parameters|HTTP Request Path Parameter}}
{{Internal|OpenAPI_Specification#Path_Parameters|OpenAPI Path Parameters}}
Also referred to as "path variable" or "variable path part".
/something/'''{id}'''/something-else


==Query==
==Query==


==Query Parameter==
===Query Parameter===
{{Internal|HTTP_Request#Query_Parameters|HTTP Request Query Parameter}}
{{Internal|OpenAPI_Specification#Query_Parameters|OpenAPI Query Parameters}}


=Method=
=Method=


A method corresponds to a [[API_Concepts#Overview|REST API]] request that is submitted by the user of the API to a [[#Resource|resource]] and to the response returned to the user. Methods are top-level constituents of a [[API_Concepts#Overview|REST API]]. Methods are defined by combinations of [[#Resource_Path|resource paths]] and [[#Operation|operations]].
A method corresponds to a [[API_Concepts#Overview|REST API]] request that is submitted by the user of the API to a [[#Resource|resource]] and to the response returned to the user. Methods belong to [[#Resource|resources]], and are defined by combinations of [[#Resource_Path|resource paths]] and [[#Operation|operations]]. The API methods represent the programming interface between the client and the API.
 
==Request==
 
A Method Request is part of the API's interface with the API's client.
 
===Request Header===
 
{{Internal|HTTP_Request#Headers|HTTP Request Header}}
{{Internal|OpenAPI_Specification#Header_Parameters|OpenAPI Header Parameters}}


=Request=
===Request Body===


==Request Header==
{{Internal|HTTP_Request#The_HTTP_Request_Body|HTTP Request Body}}
{{Internal|OpenAPI_Specification#RequestBody|OpenAPI Request Body}}


=Response=
==Response==


==Response Header==
A Method Response is part of the API's interface with the API's client.
 
===Response Header===
 
===Response Body===
 
==Per-Method Authorization==


=HTTP Protocol Semantics within a REST Application Context=
=HTTP Protocol Semantics within a REST Application Context=
Line 48: Line 101:


{{Internal|HTTP_Request#GET|HTTP GET Specification}}
{{Internal|HTTP_Request#GET|HTTP GET Specification}}
{{Internal|@GetMapping|Spring @GetMapping}}


===POST===
===POST===


Create a new [[#Resource|resource]] underneath the current one, based on the given [[#Representation|representation]].
Create a new [[#Resource|resource]] underneath the current one, based on the given [[#Representation|representation]]. POST is non-idempotent. POST is an unsafe operation.
 
<font color=darkkhaki>The appropriate response status code in case of successful creation is 201.
 
The <code>Location</code> header should contain the URL of the new resource.
</font>


Also see:
Also see:


{{Internal|HTTP_Request#POST|HTTP POST Specification}}
{{Internal|HTTP_Request#POST|HTTP POST Specification}}
{{Internal|@PostMapping|Spring @PostMapping}}


===PUT===
===PUT===


Replace the state of the given [[#Resource|resource]] with the one described in the given [[#Representation|representation]].
Replace the state of the given [[#Resource|resource]] with the one described in the given [[#Representation|representation]]. PUT is semantic opposite of [[#GET|GET]]: whereas GET requests are used to send a resource representation from server to client, PUT is used to send a resource representation from client to server. Semantically, PUT mens "put this data at this URL", replacing any data that is already there. PUT is intended to perform a wholesale '''replacement''' of the resource, rather than a partial update operation. The partial update can be performed with [[#PATCH|PATCH]]. Put is an idempotent operation. If any of the resource representation part is missing, that state will be overwritten with null.


Also see:
Also see:


{{Internal|HTTP_Request#PUT|HTTP PUT Specification}}
{{Internal|HTTP_Request#PUT|HTTP PUT Specification}}
{{Internal|@PutMapping|Spring @PutMapping}}
===PATCH===
Defined in RFC 5789.
Updates a resource by modifying '''part''' of the state of the given [[#Resource|resource]] based on the given [[#Representation|representation]]. If some bit of resource state is not mentioned in the representation, it should be left unmodified. PATCH is like [[#PUT|PUT]], but allows for fine-grained changes in resource state.
Also see:
{{Internal|HTTP_Request#PATCH|HTTP PATCH Specification}}
{{Internal|@PatchMapping|Spring @PatchMapping}}


===DELETE===
===DELETE===


Destroy the [[#Resource|resource]].
Destroy the [[#Resource|resource]].
<font color=darkkhaki>The appropriate response status code in case of successful deletion is 204.</font>


Also see:
Also see:


{{Internal|HTTP_Request#DELETE|HTTP DELETE Specification}}
{{Internal|HTTP_Request#DELETE|HTTP DELETE Specification}}
 
{{Internal|@DeleteMapping|Spring @DeleteMapping}}
===PATCH===
 
Defined in RFC 5789.
 
Modifies ''part'' of the state of the given [[#Resource|resource]] based on the given [[#Representation|representation]]. If some bit of resource state is not mentioned in the representation, it should be left unmodified. PATCH is like [[#PUT|PUT]], but allows for fine-grained changes in resource state.


===HEAD===
===HEAD===
Line 100: Line 169:


=Representation=
=Representation=
=<span id='URL'></span>Universal Resource Locator (URL)=
'''Universal Resource Locator'''
=<span id='URI'></span>Universal Resource Identifier (URI)=
'''Universal Resource Identifier'''


=<span id='REST'></span>Representational State Transfer (REST)=
=<span id='REST'></span>Representational State Transfer (REST)=
Line 126: Line 187:


=<span id='Content_Type'></span><span id='MIME_Type'></span>Media Type=
=<span id='Content_Type'></span><span id='MIME_Type'></span>Media Type=
{{External|[https://en.wikipedia.org/wiki/Media_type Wikipedia Media Type]}}
{{External|[https://en.wikipedia.org/wiki/Media_type Wikipedia Media Type]}}
{{External|http://www.iana.org/assignments/media-types/media-types.xhtml}}


A '''media type''', also called '''media-type''', '''content type''' or '''MIME type''' is a two-part string identifying the format of a document. Usually, knowing a document's format allows us to parse it. IANA (Internet Assigned Numbers Authority) is the official authority for the standardization and publication of media types.
A '''media type''', also called '''media-type''', '''content type''' or '''MIME type''' is a two-part string identifying the format of a document. Usually, knowing a document's format allows us to parse it. IANA (Internet Assigned Numbers Authority) is the official authority for the standardization and publication of media types. Within the context of REST, the media type is a format of a request and response body. Media types are specified by [https://tools.ietf.org/html/rfc6838 RFC6838 -  Media Type Specifications and Registration Procedures].


The media type string consists of a type and a subtype. The subtype can be further be structured into a tree. A media type can optionally define a suffix and parameters:
The media type string consists of a type and a subtype. The subtype can be further be structured into a tree. A media type can optionally define a suffix and parameters:
Line 144: Line 205:


* [[Media Type Support in Spring]]
* [[Media Type Support in Spring]]
* [[OpenAPI#Media_Types|Media Type Support in OpenAPI]]
=OpenAPI Operation Declaration and Implementation Examples=
{{Internal|OpenAPI_Specification_Path#Operation_Declaration_and_Implementation_Examples|OpenAPI Examples}}

Latest revision as of 23:53, 14 February 2024

External

Internal

Overview

HTTP APIs often use the Representational State Transfer (REST) architectural style, which is developed around the following principles:

  • Organize the API around resources.
  • Communicate actions using HTTP methods.
  • Model response around standard HTTP status codes.

API

API Concepts

Uniform Resource Locator (URL)

URL

Uniform Resource Identifier (URI)

URI

Uniform Resource Name (URN)

URN

Endpoint

A REST API endpoint is the interaction point where a specific URL is configured to receive web requests.

Best Practices for Naming REST API URIs

Resource

A resource is a logical entity that an application can access through a resource path. A resource is a top-level constituent of a REST API. Resources are sometimes referred to as the nouns of the API. A resource has a number of methods.

TODO: receive data from client via path, Spring REST Concepts: Spring_REST_Concepts#Via_Path

Resource Path

Path Parameter, Path Variable, Variable Path Part

HTTP Request Path Parameter
OpenAPI Path Parameters

Also referred to as "path variable" or "variable path part".

/something/{id}/something-else

Query

Query Parameter

HTTP Request Query Parameter
OpenAPI Query Parameters

Method

A method corresponds to a REST API request that is submitted by the user of the API to a resource and to the response returned to the user. Methods belong to resources, and are defined by combinations of resource paths and operations. The API methods represent the programming interface between the client and the API.

Request

A Method Request is part of the API's interface with the API's client.

Request Header

HTTP Request Header
OpenAPI Header Parameters

Request Body

HTTP Request Body
OpenAPI Request Body

Response

A Method Response is part of the API's interface with the API's client.

Response Header

Response Body

Per-Method Authorization

HTTP Protocol Semantics within a REST Application Context

Operations

A resource's operations are defined by HTTP verbs:

GET

Get a representation of a resource.

Also see:

HTTP GET Specification
Spring @GetMapping

POST

Create a new resource underneath the current one, based on the given representation. POST is non-idempotent. POST is an unsafe operation.

The appropriate response status code in case of successful creation is 201.

The Location header should contain the URL of the new resource.

Also see:

HTTP POST Specification
Spring @PostMapping

PUT

Replace the state of the given resource with the one described in the given representation. PUT is semantic opposite of GET: whereas GET requests are used to send a resource representation from server to client, PUT is used to send a resource representation from client to server. Semantically, PUT mens "put this data at this URL", replacing any data that is already there. PUT is intended to perform a wholesale replacement of the resource, rather than a partial update operation. The partial update can be performed with PATCH. Put is an idempotent operation. If any of the resource representation part is missing, that state will be overwritten with null.

Also see:

HTTP PUT Specification
Spring @PutMapping

PATCH

Defined in RFC 5789.

Updates a resource by modifying part of the state of the given resource based on the given representation. If some bit of resource state is not mentioned in the representation, it should be left unmodified. PATCH is like PUT, but allows for fine-grained changes in resource state.

Also see:

HTTP PATCH Specification
Spring @PatchMapping

DELETE

Destroy the resource.

The appropriate response status code in case of successful deletion is 204.

Also see:

HTTP DELETE Specification
Spring @DeleteMapping

HEAD

Get the headers that would be sent along with a representation of this resource, but not the representation itself. This method is mostly used when a client explores the API.

Also see:

HTTP HEAD Specification

OPTIONS

Discover which methods this resource responds to. This method is mostly used when a client explores the API.

Also see:

HTTP OPTIONS Specification

LINK

UNLINK

Representation

Representational State Transfer (REST)

RWA page 32

Multipurpose Internet Mail Extension (MIME)

MIME is an internet standard that extends the format of e-mail to support text in character sets other then ASCII, non-text attachments, such as audio, video, images, application programs, etc., message bodies with multiple parts and header information in non-ASCII characters sets. MIME is specified in six linked RFCs: RFC 2045, RFC 2046, RFC 2047, RFC 4288, RFC 4289 and RFC 2049.

MIME is relevant to HTTP. The content types define by MIME are used in the definition of HTTP content. HTTP clients use MIME content type headers to indicate the desired application to process the specific type of content they send. HTTP servers insert MIME content type information in all their responses.

MIME defines the following headers:

  • MIME-Version
  • Content-Type
  • Content-Disposition
  • Content-Transfer-Encoding

Media Type

Wikipedia Media Type
http://www.iana.org/assignments/media-types/media-types.xhtml

A media type, also called media-type, content type or MIME type is a two-part string identifying the format of a document. Usually, knowing a document's format allows us to parse it. IANA (Internet Assigned Numbers Authority) is the official authority for the standardization and publication of media types. Within the context of REST, the media type is a format of a request and response body. Media types are specified by RFC6838 - Media Type Specifications and Registration Procedures.

The media type string consists of a type and a subtype. The subtype can be further be structured into a tree. A media type can optionally define a suffix and parameters:

type "/" [tree "." ] subtype ["+" suffix] *[";" parameter]

The currently registered types are: "application", "audio", "example", "font", "image", "message", "model", "multipart", "text" and "video".

An HTML file may be designated as:

text/html; charset=UTF-8

Media Type Support

OpenAPI Operation Declaration and Implementation Examples

OpenAPI Examples