This document describes the Examples Documentation Asciidoctor Quick Start.

1. Introduction

1.1. Common concept

The Examples Documentation Asciidoctor Quick Start is organized around REST and built using the RxMicro framework.
The Examples Documentation Asciidoctor Quick Start has predictable resource-oriented URLs, accepts and returns JSON-encoded requests/responses, and uses standard HTTP response codes, and verbs.

For requests and responses without body the Examples Documentation Asciidoctor Quick Start returns the empty body instead of the empty json object: {}.
So the Examples Documentation Asciidoctor Quick Start could accept and return json object or empty body only.

You could use your favorite HTTP/REST library for your programming language to use The Examples Documentation Asciidoctor Quick Start.

1.2. HTTP Verbs

The Examples Documentation Asciidoctor Quick Start uses HTTP verbs appropriate to each action.

Verb Description

GET

Retrieving resource(s).

POST

Creating resource(s).

PUT

Full updating resource(s).

PATCH

Partial updating resource(s).

DELETE

Deleting resource(s).

1.3. Error model

The Examples Documentation Asciidoctor Quick Start uses conventional HTTP response codes to indicate the success or failure of an API request.
In general:

  • Codes in the 2xx range indicate success.

  • Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted or has invalid format, etc.).

  • Codes in the 5xx range indicate an internal error with the Examples Documentation Asciidoctor Quick Start servers.

Successes differ from errors in that their body may not be a simple response object with a message.

If error occurs, the Examples Documentation Asciidoctor Quick Start returns correspond HTTP status code and standard JSON error model:

{
    "message": "'name' is required"
}

Message field provides detailed cause of the arisen error.

By default, the Examples Documentation Asciidoctor Quick Start hides the cause of the arisen server error.
Thus, if internal error occurs (Errors with code in the 5xx range), the value of message field will be Internal Server Error, Gateway Timeout, etc.
To activate the displaying of the detailed cause of the arisen server error, start REST server with RestServerConfig.hideInternalErrorMessage=false option.

1.4. Default Not Found Handler

If The Examples Documentation Asciidoctor Quick Start does not have a route that matches the current HTTP request, by default it invokes Default Not Found Handler and returns a HTTP/1.1 400 Bad Request response with default JSON body:

{
    "message": "Handler not found"
}

Other REST frameworks typically use a HTTP/1.1 404 Not Found response to inform the client of a missing request handler.
However, when developing the REST-based micro services, HTTP/1.1 404 Not Found response is very often used as a business value. For example, if the resource requested by its identifier is absent at the database, then the client receives HTTP/1.1 404 Not Found response.

Thus, on the client side, if the server returns HTTP/1.1 404 Not Found response, it is not possible to determine the reason: there is no request handler or there is no object in the database.
Therefore, in order to unambiguously determine the cause of the error, the RxMicro framework by default uses exactly HTTP/1.1 400 Bad Request response in case the handler is absent.

Default Not Found Handler could be configured.
(If it necessary You could use HTTP/1.1 404 Not Found response status code instead of HTTP/1.1 400 Bad Request).

To use custom Default Not Found Handler start REST server with RestServerConfig.handlerNotFoundErrorStatusCode=${CUSTOM_STATUS_CODE} and/or RestServerConfig.handlerNotFoundErrorMessage=${CUSTOM_MESSAGE} options, where:

  • ${CUSTOM_STATUS_CODE} - custom status code, which will be used instead of HTTP/1.1 400 Bad Request;

  • ${CUSTOM_MESSAGE} - custom message, which will be used instead of "Handler not found";

1.5. License

The Examples Documentation Asciidoctor Quick Start is licensed under the Apache License Version 2.0.

1.6. Specification

The Examples Documentation Asciidoctor Quick Start documentation built using Ascii Doctor markup language.

2. Hello World Micro Service

2.1. GET /

2.1.1. Request

2.1.1.1. HTTP Request Example
GET / HTTP/1.1
Accept: application/json
Content-Length: 0

2.1.2. Response 200

2.1.2.1. HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 25
Request-Id: 62jJeu8x1310662

{
  "message": "string"
}
2.1.2.2. HTTP Response Headers Description

Name

Type

Restrictions

Description

Request-Id

string

  • required: true

  • unique: true

An unique request string identifier.

Read more:
2.1.2.3. HTTP Response Body Parameters Description

Name

Type

Restrictions

Description

message

string

  • optional: true
2.1.2.4. HTTP Response Body JSON Schema

(Read more about JSON Schema)

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "examples": [
        "string"
      ]
    }
  },
  "minProperties": 0,
  "maxProperties": 1
}

2.1.3. Response 500

If internal server error detected.

2.1.3.1. HTTP Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 33
Request-Id: 62jJeu8x1310662

{
  "message": "Internal Error"
}
2.1.3.2. HTTP Response Headers Description

Name

Type

Restrictions

Description

Request-Id

string

  • required: true

  • unique: true

An unique request string identifier.

Read more:
2.1.3.3. HTTP Response Body Parameters Description

Name

Type

Restrictions

Description

message

string

  • required: true

Internal Server Error value (by default) or the detailed cause of the arisen internal server error.

Read more: