1. Terminology

2. Rest convention

2.1. HTTP verbs

Speakers Service tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb

Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

PUT

Used to update an existing resource, full updates only

DELETE

Used to delete an existing resource

2.2. HTTP status codes

Differ Service tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

409 Conflict

The request could not be completed due to a conflict with the current state of the target resource.

422 Unprocessable Entity

Validation error has happened due to processing the posted entity.

3. Endpoints

3.1. DiffService

3.1.1. Get diff between versions

Curl example
$ curl 'http://localhost:8080/v1/differ?left=0001&right=0002' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json'
HTTP Request
GET /v1/differ?left=0001&right=0002 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080
HTTP Request parameters
Parameter Description

left

An old version of API

right

A new version of API
HTTP Response
Success HTTP responses
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 179

{
  "full" : {
    "home" : {
      "info" : {
        "description" : "API for fetching user related information"
      }
    }
  },
  "onlyOnLeft" : { },
  "onlyOnRight" : { }
}
Success response fields
Path Type Description

full

{}

Entities presented in both versions

onlyOnLeft

{}

Entities only on left version

onlyOnRight

{}

Entities only on right version
Response body
{
  "full" : {
    "home" : {
      "info" : {
        "description" : "API for fetching user related information"
      }
    }
  },
  "onlyOnLeft" : { },
  "onlyOnRight" : { }
}
Not Found HTTP responses
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 68

{
  "message" : "No version 0002 file was found",
  "cause" : null
}
Success response fields
Path Type Description

message

String

Error description, can show to user

cause

java.lang.Exception

If any error occurred
Response body
{
  "message" : "No version 0002 file was found",
  "cause" : null
}