Skip to content

User.md

Latest commit

 

History

History
323 lines (225 loc) · 8.95 KB

User.md

File metadata and controls

323 lines (225 loc) · 8.95 KB

test v0.13.0

RESTful web API Documentation Generator

Header .md File

This is the content of the header.md file.

Table of contents

this quote is prepended to this doc using a file prepend.md

User

Change a User

Back to top

This function has same errors like POST /user, but errors not defined again, they were included with "apiErrorStructure"

PUT /user/:id

Parameters - Parameter

Name Type Description
id Number

id of the user.

Request Body

Name Type Description
name String

Name of the User.
avatar File

Upload avatar.

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNameTooShort

Minimum of 5 characters required.

Error response example

Error response example - Response (example):

HTTP/1.1 400 Bad Request
{
  "error": "UserNameTooShort"
}

Create a new User

Back to top

In this case "apiErrorStructure" is defined and used. Define blocks with params that will be used in several functions, so you dont have to rewrite them.

POST /user

Request Body

Name Type Description
age Number

Age of the User
name String

Name of the User

Default value: Caroline
extraInfo.hireDate Date

Date when user was hired
extraInfo.hireDateWithDefault Date

Date when user was hired with default

Default value: 2021-09-01
extraInfo.nickname String

Nickname of the user
extraInfo.isVegan Boolean

Is the user vegan? (boolean with default)

Default value: true
extraInfo.isAlive Boolean

Is the user alive? (boolean with no default)
extraInfo.secrets.crush String

The user secret crush
extraInfo.secrets.hair Number

Number of hair of user

Default value: 1000

Success response

Success response - Success 200

Name Type Description
id Number

The new Users-ID.

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNameTooShort

Minimum of 5 characters required.

Error response example

Error response example - Response (example):

HTTP/1.1 400 Bad Request
{
  "error": "UserNameTooShort"
}

Delete user

Back to top

Be careful! This will remove all the data associated with that user!

DELETE /user/:id

Headers - Header

Name Type Description
Authorization String

The token can be generated from your user profile.

Header examples

Header-Example

"Authorization: token 5f048fe"

Parameters - Parameter

Name Type Description
id Number

id of the user.

Examples

Curl example

curl -X DELETE -H "Authorization: token 5f048fe" -i https://api.example.com/user/4711

Javascript example

const client = AcmeCorpApi('5f048fe');
const user = client.deleteUser(42);

Python example

client = AcmeCorpApi.Client(token="5f048fe")
user = client.delete_user(42)

Success response

Success response - Success 200

Name Type Description
result String

ok if everything went fine.
nullableField String optional

This response field is not always there (can be null).

Success response example

Success response example - Success-Example

HTTP/1.1 200 OK
{
    "result": "ok"
}

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNotFound

The id of the User was not found.

Error response - 500 Internal Server Error

Name Type Description
InternalServerError

The server encountered an internal error.

Error response example

Error response example - Response (example):

HTTP/1.1 401 Not Authenticated
{
  "error": "NoAccessRight"
}

Read data of a User

Back to top

Compare version 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.

GET /user/:region/:id/:opt

Headers - Header

Name Type Description
Authorization String

The token can be generated from your user profile.
X-Apidoc-Cool-Factor String

Some other header with a default value.

Header examples

Header-Example

"Authorization: token 5f048fe"

Parameters - Parameter

Name Type Description
id Number

User unique ID
region String

User region

Default value: fr-par
opt String optional

An optional param

Examples

Curl example

curl -H "Authorization: token 5f048fe" -i https://api.example.com/user/fr-par/4711
curl -H "Authorization: token 5f048fe" -H "X-Apidoc-Cool-Factor: superbig" -i https://api.example.com/user/de-ber/1337/yep

Javascript example

const client = AcmeCorpApi('5f048fe');
const user = client.getUser(42);

Python example

client = AcmeCorpApi.Client(token="5f048fe")
user = client.get_user(42)

Success response

Success response - Success 200

Name Type Description
id Number

The Users-ID.
registered Date

Registration Date.
name String

Fullname of the User.
nicknames String[]

List of Users nicknames (Array of Strings).
profile Object

Profile data (example for an Object)
profile.age Number

Users age.
profile.image String

Avatar-Image.
options Object[]

List of Users options (Array of Objects).
options.name String

Option Name.
options.value String

Option Value.

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNotFound

The id of the User was not found.

Error response - 500 Internal Server Error

Name Type Description
InternalServerError

The server encountered an internal error

Error response example

Error response example - Response (example):

HTTP/1.1 401 Not Authenticated
{
  "error": "NoAccessRight"
}

Thank a user: this is quite a long name indeed

Back to top

This is here to have a long name in the left menu.

POST /user/:id

Footer .md File

This is the content of the footer.md file.