[API Documentation Example]

View original Gist on GitHub

Tags: #API #documentation

API Documentation Example.md

Example Auth API

A standalone HTTP service that handles authenticating users between AWS Cognito and the legacy WebApp.

Location

The Example Auth API is available through the API Gateway at these URL prefixes:

https://api.example.com/auth (production)
https://api-stage.example.com/auth (staging)

Endpoints

/account/confirm
/admin/email/change
/admin/status/change
/admin/user/create
/admin/user/get
/email/change
/email/confirm
/password/change
/password/confirm
/signin
/signin/social
/signout
/tokens/verify
/user/signup
/users/filter/email
/users/filter/username

`/account/confirm`

Confirms registration of a user (i.e. they’re ‘verified’).

Request

POST https://api.example.com/auth/account/confirm

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

code=...&username=...

Params

code: verification code (provided by AWS)
username: user to verify

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`MISSING_PARAMS`
`400`	`SIGN_UP_CONFIRMATION_FAILED`	Multiple causes, see AWS documentation
`500`	`SIGN_UP_CONFIRMATION_FAILED`	AWS has returned an internal server error

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/admin/email/change`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/admin/status/change`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/admin/user/create`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/admin/user/get`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/email/change`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/email/confirm`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/password/change`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/password/confirm`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/signin`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/signin/social`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/signout`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/tokens/verify`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/user/signup`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/users/filter/email`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}

`/users/filter/username`

…

Request

METHOD https://api.example.com/auth/...

Headers

Content-Type: application/x-www-form-urlencoded (required)

Body

key=value&key=value

Params

...: …

Successful Response

200 OK

{
  "status": "success"
}

Errors

Status	Message	Notes
`400`	`SOME_THING`	…
`400`	`SOME_OTHER_THING`

Every error response takes the form

{
  "status": "error",
  "code": ERROR_STATUS_CODE,
  "context": "ERROR_MESSAGE"
}