A standard way to document your REST API

API-Documentation.md

Endpoint title get

Url

[GET] api/endpoint/:id/

Description

Natural description of what the API do

Url Parameters

Field	Data Type	Required	Description
param_1	string	no	a simple txt
param_2	choices	no	do something with choices, see force parameter choices for more info
param_3	int	yes	a number

param_2 Parameter Choices

Parameter Content	Description
true	this is true
false	this is false

Example

[GET] api/endpoint/:id/?param_1=hello world

Example Response

HTTP 200 OK

{
    "status": {
        "success": true,
        "errors": []
    },
    "result": [
        {
            "id": "1",
            "code": "72d9e8b5-b225-476c-a83e-50cdb720e4g6",
            "service_name": "fina"
        },
        {
            "id": "2",
            "code": "19d9e8b5-b225-476c-a83e-50cdb720f989",
            "service_name": null
        }        
    ]
}

Errors

Http Code	Verbose Code	Internal Code	Description
400	Bad Request		Generic error
400	Bad Request	31	Server failed to update

Error Response

{
    "status": {
        "success": false,
        "errors": [
            {
                "code": 30,
                "message": "The remote server failed to update"
            }
        ]
    },
    "result": []
}

Http Code	Verbose Code	Internal Code	Description
400	Bad Request	40	The remote service is currently unavailable

Error Response

{
    "status": {
        "success": false,
        "errors": [
            {
                "code": 40,
                "message": "The remote service is currently unavailable"
            }
        ]
    },
    "result": []
}

Http Code	Verbose Code	Internal Code	Description
401	Unauthorized		Missing authentication token
403	Forbidden		The user don't have the permissions to do that action
404	Not Found		The obj that you are looking for does not exist

Endpoint title post

Url

[POST] /api/endpoint/

Description

Natural description of what the API do

Url Parameters

Field	Data Type	Required	Description
param_1	string	no	a simple txt

Body Parameters

Field	Data Type	Required	Description
name	string	yes	The name of the person
last_name	string	yes	The surname of the person
age	int	no	The age of the person

Example

[POST] /api/endpoint/?param_1=hello world again

Example Request Body

{
    "name": "Mario",
    "last_name": "Rossi",
    "age": 20
}

Example Response

HTTP 201 CREATED

{
    "status": {
        "success": true,
        "errors": []
    },
    "result": {
        "id": 2,
        "name": "Mario",
        "last_name": "Rossi",
        "age": 20
    }
}