Overview

HTTP verbs

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

Verb Usage

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
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

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

Status code Usage

Status code	Usage
`200 OK`	The request completed successfully
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s `Location` header
`204 No Content`	An update to an existing resource has been applied successfully
`400 Bad Request`	The request was malformed. The response body will include an error providing further information
`401 Unauthorized`	The requested resource requires authentication
`403 Forbidden`	You have no permission on requested resource
`404 Not Found`	The requested resource did not exist
`500 Internal server error`	The server encountered an unexpected condition that prevented it from fulfilling the request
`502 Bad Gateway`	The server, while acting as a gateway or proxy, received an invalid response from the upstream server

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The requested resource requires authentication

403 Forbidden

You have no permission on requested resource

404 Not Found

The requested resource did not exist

500 Internal server error

The server encountered an unexpected condition that prevented it from fulfilling the request

502 Bad Gateway

The server, while acting as a gateway or proxy, received an invalid response from the upstream server

Headers

Every request should have the following headers:

Name Description

Name	Description
`Accept-Language`	Advertises which languages the client is able to understand, and which locale variant is preferred
`Authorization`	TS Digital access token (e.g. Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.Et9HFtf9R3GEMA0IICOfFMVXY7kkTX1wr4qCyhIf58U)
`User-Agent`	User agent string (e.g. Lynfa/5.0 (Windows NT x.y; rv:10.0) Paghe/1.0)
`X-App-Namet`	Caller application name (e.g. TS000)
`X-App-Version`	Caller application version (e.g. 1.0.2)

Accept-Language

Advertises which languages the client is able to understand, and which locale variant is preferred

Authorization

TS Digital access token (e.g. Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.Et9HFtf9R3GEMA0IICOfFMVXY7kkTX1wr4qCyhIf58U)

User-Agent

User agent string (e.g. Lynfa/5.0 (Windows NT x.y; rv:10.0) Paghe/1.0)

X-App-Namet

Caller application name (e.g. TS000)

X-App-Version

Caller application version (e.g. 1.0.2)

Optional headers:

Name Description

Name	Description
`X-Correlation-ID`	Multiple x-request-id correlation identifier (e.g 6a83ff97-ac20-47c8-bbe3-1f3319cf9aa6)
`X-Item-ID`	TS Digital item identifier that made the request
`X-Manager-ID`	TS Digital item identifier that manages the one provided in x-item-id
`X-Request-ID`	Unique request identifier (e.g. cjqqbbezk139w08878awoj1p0)
`X-User-ID`	Identifier of local TS Digital user making the request

X-Correlation-ID

Multiple x-request-id correlation identifier (e.g 6a83ff97-ac20-47c8-bbe3-1f3319cf9aa6)

X-Item-ID

TS Digital item identifier that made the request

X-Manager-ID

TS Digital item identifier that manages the one provided in x-item-id

X-Request-ID

Unique request identifier (e.g. cjqqbbezk139w08878awoj1p0)

X-User-ID

Identifier of local TS Digital user making the request

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

Path	Type	Description
`status`	`String`	Http Status description
`code`	`String`	Http Status code
`timestamp`	`String`	Response time as ISO date string
`message`	`String`	Error description

status

String

Http Status description

code

String

Http Status code

timestamp

String

Response time as ISO date string

message

String

Error description

For example, a request that attempts to apply a non-existent tag to a note will produce a 400 Bad Request response:

{
    "status": "BAD_REQUEST",
    "code": "400",
    "timestamp": "02-12-2019 21:00:25",
    "message": "E' necessario filtrare per ownerId",
    "subErrors": null
}

RESTful Notes uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

B2BRead v15.1.24 API Guide