Web Service - Representational State Transfer (REST|RESTful) Web services


Representational State Transfer (REST) Web services, or “RESTful” Web services describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP.

There is no client context being stored server side (no Sessions). REST is a stateless.

REST is easier to build and consume than using SOAP-services.

REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs. A client accesses the resource using the URI, a standardized fixed set of methods, and a representation of the resource is returned. The client is said to transfer state with each new resource representation.

Rest is often the base technology behind micro-services


Object Address

Objects in a typical REST system are addressable by URI and interacted with using verbs in the HTTP protocol.

  • An HTTP GET to a particular URI fetches an object and returns a server-specified set of fields.
  • An HTTP PUT edits an object;
  • An HTTP DELETE deletes an object; and so on.

Because of multiple round-trips and over-fetching, applications built in the REST style inevitably end up building ad hoc endpoints.

Ad Hoc Endpoints

Many applications have no formalized client-server contract. Product developers access server capabilities through ad hoc endpoints and write custom code to fetch the data they need. (They end up with a custom endpoint per view).

HTTP Request Method

REST makes use of the HTTP request methods:

  • GET - Read requests
  • PUT- Modify Request
  • POST- Create Request
  • DELETE - Delete Request

When you see an application making PUT or GET requests over HTTP or HTTPS, that’s REST.

Context and security

A RESTful interface does not store any information about a particular user's session.

Every request authentication is basic. See Http - Authorization Header (authentication entries)


version can be specified:

  • in the url
  • or as a query string. example: api-version: 2015-06-15


There is actually two schema file format that may defines your Rest API:


Contract first

In a contract first / contract-driven development:

  • the schema file is defined first.
  • boilerplate code (ie POJOs) is generated from it
  • client / documentation (known as console) is generated from it
  • and /or every request can be also be controlled from it


  • the schema file must be kept up-to-date.
  • once generated, you can't regenerate the boilerplate code
  • not really flexible

Code First

In a code first development:

  • the code is annotated with annotation or comment
  • a schema file can then be generated (Example: from jax-rs swagger-core)
  • client / documentation (known as console) can be generated from:

Documentation generator:







Via the setting of a proxy, you can set up what's called a mock-server


Test in container. See test-suite with Blog

List of Known Public API

Documentation / Reference

Powered by ComboStrap