Overview

This document contains the documentation for the REST API to consume the human service. This documentation was built on top of version 1.0.0-SNAPSHOT using Java version 11 and Spring Boot version 2.6.1. You can see the source code here github.

1. HTTP verbs

The services developed for the project try to comply with the HTTP and REST conventions in the use of verbs HTTP.

Verb Usage

GET

Used to retrieve an existing resource.

POST

Used to create a new resource.

PUT

Used to update an existing resource.

DELETE

Used to delete an existing resource.

2. HTTP status codes

The services developed for the project try to comply with the HTTP and REST conventions in the use of codes of HTTP status.

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 request resource is restricted. The requested resource is restricted and requires authentication.

404 Not Found

The requested resource does not exist.

405 Method Not Allowed

The requested method not supported.

415 Unsupported Media Type

The Content type is empty or invalid.

422 Unprocessable Entity

The resource already exist.

5XX Server Error

Internal server error, the request cannot be processed.

3. Headers

Every response has the following header(s):

Name Description

Content-Type

The Content-Type of the payload, default is application/json.

4. Errors

Whenever an error response (http 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

timestamp

Long

The time, in milliseconds, at which the error occurred.

status

Number

The HTTP status code.

error

String

The HTTP status code description.

message

String

A description of the cause of the error.

path

String

The path to which the request was made.

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

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
    "timestamp": "2022-02-12T18:14:55.731+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "User not found",
    "path": "/users/{id}"
}

5. Error types

Type Status code Error message

AccountAlreadyExistException

422

Account already exist.

UserAlreadyExistException

422

User already exist.

UserNotFoundException

404

User not found.

Resources

6. User

The user resource is used to manage information from a user.

6.1. Get User By Identifier

A GET request will get user Info.

6.2. Path Parameters

Table 1. /users/{id}
Parameter Description

id

User identifier

6.2.1. Response Fields

Path Type Optional Description

id

Number

false

User identifier

name

String

false

User name

lastname

String

false

User lastname

age

Number

false

User age

email

String

false

User email

accounts

Array

true

Related user accounts

6.2.2. Curl Request

$ curl 'http://example.com:8080/users/1' -i -X GET \
    -H 'Content-Type: application/json'

6.2.3. Http Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 113

{
  "id" : 1,
  "name" : "David",
  "lastname" : "Bernal",
  "age" : 31,
  "email" : "leo.bernal1946@gmail.com"
}

6.3. Post Create User

A POST request will create a new user.

6.3.1. Request Fields

Path Type Optional Description Constraints Example Value

id

Number

true

User identifier

-

name

String

false

User name

Must not be null

Trinidad

lastname

String

false

User lastname

Must not be null

Rivas

age

Number

false

User age

Must not be null

34

email

String

false

User email

Must be a well-formed email address- Must not be null

mail@example.com

accounts

String

true

Related user accounts

-

6.3.2. Response Fields

Path Type Optional Description

id

Number

false

User identifier

name

String

false

User name

lastname

String

false

User lastname

age

Number

false

User age

email

String

false

User email

accounts

String

true

User email

6.3.3. Curl Request

$ curl 'http://example.com:8080/users' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "Andy",
  "lastname" : "Jackson",
  "age" : 40,
  "email" : "email@example.com"
}'

6.3.4. Http Response

HTTP/1.1 201 Created
Location: http://example.com:8080/users/3
Content-Type: application/json
Content-Length: 106

{
  "id" : 3,
  "name" : "Andy",
  "lastname" : "Jackson",
  "age" : 40,
  "email" : "email@example.com"
}

6.4. Delete User

A DELETE request will delete an existing user.

6.5. Path Parameters

Table 2. /users/{id}
Parameter Description

id

User identifier

6.5.1. Curl Request

$ curl 'http://example.com:8080/users/1' -i -X DELETE \
    -H 'Content-Type: application/json'

6.5.2. Http Response

HTTP/1.1 202 Accepted

6.6. Get Users

A GET request will get all existing users.

6.6.1. Curl Request

$ curl 'http://example.com:8080/users' -i -X GET \
    -H 'Content-Type: application/json'

6.6.2. Response Fields

Path Type Optional Description

[].id

Number

false

User identifier

[].name

String

false

User name

[].lastname

String

false

User lastname

[].age

Number

false

User age

[].email

String

false

User email

[].accounts

String

true

User email

6.6.3. Http Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 228

[ {
  "id" : 1,
  "name" : "David",
  "lastname" : "Bernal",
  "age" : 31,
  "email" : "leo.bernal1946@gmail.com"
}, {
  "id" : 2,
  "name" : "Oscar",
  "lastname" : "Smith",
  "age" : 31,
  "email" : "oscar.smith@gmail.com"
} ]

7. Account

7.1. Post Create User Account

A POST request will create a new user account.

7.1.1. Request Fields

Path Type Optional Description Constraints Example Value

id

String

true

Account type

-

type

String

false

Account type

Must not be null

DEBIT, CREDIT

number

String

false

Account number

Must not be null- Size must be between 16 and 16 inclusive

4909914807265711

balance

Number

true

Account balance

Must be positive or zero

$8,933.95

7.1.2. Response Fields

Path Type Optional Description

id

Number

false

Account identifier

type

String

false

Account type

number

String

false

Account number

balance

Number

true

Account balance

7.1.3. Curl Request

$ curl 'http://example.com:8080/users/1/accounts' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "type" : "DEBIT",
  "number" : "4909914807265711"
}'

7.1.4. Http Response

HTTP/1.1 201 Created
Location: http://example.com:8080/users/1/accounts/3
Content-Type: application/json
Content-Length: 67

{
  "id" : 3,
  "type" : "DEBIT",
  "number" : "4909914807265711"
}

7.2. Get User Accounts

A GET request will get user accounts Info.

7.3. Path Parameters

Table 3. /users/{id}/accounts
Parameter Description

id

User identifier

7.3.1. Response Fields

Path Type Optional Description

[].id

Number

false

Account identifier

[].type

String

false

Account type

[].number

String

false

Account number

[].balance

Number

true

Account balance

7.3.2. Curl Request

$ curl 'http://example.com:8080/users/1/accounts' -i -X GET \
    -H 'Content-Type: application/json'

7.3.3. Http Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 163

[ {
  "id" : 1,
  "type" : "DEBIT",
  "number" : "4909914807265710",
  "balance" : 8933.95
}, {
  "id" : 3,
  "type" : "DEBIT",
  "number" : "4909914807265711"
} ]