This web page is an example of the documentation output generated by the Explicit gem.
You can find the source code and complete documentation here.

Registration

POST http://localhost:3000/api/v1/registrations

Attempts to register a new user in the system. Email address must be unique. If registration succeeds an authentication token is returned. Use this token to authenticate requests with the header Authorization: Bearer <token>.

Params

name string

▲ ▼

Full name

not empty

email_address string

▲ ▼

Email address used to login. Case insensitive.

format /\A[a-zA-Z0-9.!\#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/

case insensitive

password string

▲ ▼

Minimum 8 characters. No other rules.

min_length 8

terms_of_use boolean

▲ ▼

The following values are accepted:

true "true" "on" "1" 1

token string

Example

curl -XPOST "http://localhost:3000/api/v1/registrations" \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "name": "Yukihiro Matsumoto",
  "email_address": "matz@ruby.org",
  "password": "mystrongpassword#'\"",
  "terms_of_use": true
}
EOF

# 200 OK
{
  "token": "62JwTHviDTCK4QYWa2gs"
}

error "email_already_taken"

OR

error "invalid_params"

params object

▲ ▼

An object containing error messages for all invalid params

Keys string

Values string

Examples (/)

curl -XPOST "http://localhost:3000/api/v1/registrations" \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "name": "Luiz",
  "email_address": "luiz@example.org",
  "password": "mystrongpassword",
  "terms_of_use": true
}
EOF

# 422 Unprocessable Content
{
  "error": "email_already_taken"
}

curl -XPOST "http://localhost:3000/api/v1/registrations"

# 422 Unprocessable Content
{
  "error": "invalid_params",
  "params": {
    "name": "must be a string",
    "email_address": "must be a string",
    "password": "must be a string",
    "terms_of_use": "must be accepted"
  }
}

Log in

POST http://localhost:3000/api/v1/sessions

Attempts to sign in a user to the system. If sign in succeeds an authentication token is returned. Use this token to authenticate requests with the header Authorization: Bearer <token>.

Params

email_address string

▲ ▼

format /\A[a-zA-Z0-9.!\#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/

case insensitive

password string

▲ ▼

min_length 8

token string

Example

curl -XPOST "http://localhost:3000/api/v1/sessions" \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "email_address": "luiz@example.org",
  "password": "mystrongpassword"
}
EOF

# 200 OK
{
  "token": "HjO0krVQDjwDSDY0XRZM"
}

error "invalid_credentials"

OR

error "invalid_params"

params object

▲ ▼

An object containing error messages for all invalid params

Keys string

Values string

Examples (/)

curl -XPOST "http://localhost:3000/api/v1/sessions" \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "email_address": "non-existing-user@example.org",
  "password": "any-password"
}
EOF

# 422 Unprocessable Content
{
  "error": "invalid_credentials"
}

curl -XPOST "http://localhost:3000/api/v1/sessions"

# 422 Unprocessable Content
{
  "error": "invalid_params",
  "params": {
    "email_address": "must be a string",
    "password": "must be a string"
  }
}

curl -XPOST "http://localhost:3000/api/v1/sessions" \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "email_address": "luiz@example.org",
  "password": "wrong-password"
}
EOF

# 422 Unprocessable Content
{
  "error": "invalid_credentials"
}

Log out

DELETE http://localhost:3000/api/v1/sessions

Revokes the authentication token used to authenticate the request, which prevents the token from being used in the future.

Headers

Authorization string

▲ ▼

format /Bearer [a-zA-Z0-9]{20}/

message "session revoked"

error "unauthorized"

Create article

POST http://localhost:3000/api/v1/articles

Headers

Authorization string

▲ ▼

format /Bearer [a-zA-Z0-9]{20}/

Params

title string

▲ ▼

not empty

content string

▲ ▼

not empty

published_at string

▲ ▼

Value must be a valid date time according to ISO 8601. For example: "2024-12-10T14:21:00Z"

article object

▲ ▼

id integer

▲ ▼

not negative

title string

▲ ▼

not empty

content string

▲ ▼

not empty

published_at string

▲ ▼

When published_at is null it means the article is a draft.
When published_at is a moment in the future it means the article is scheduled to be published.
When published_at is a moment in the past it means the article is published and can be read by everyone.

Value must be a valid date time according to ISO 8601. For example: "2024-12-10T14:21:00Z"

read_count integer

▲ ▼

only positive

Examples (/)

curl -XPOST "http://localhost:3000/api/v1/articles" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer RY78YxmifxYXpAFOM8wq" \
-d @- << EOF
{
  "title": "Article title",
  "content": "Article content"
}
EOF

# 201 Created
{
  "article": {
    "id": 594821791,
    "title": "Article title",
    "content": "Article content",
    "published_at": null,
    "read_count": 0
  }
}

curl -XPOST "http://localhost:3000/api/v1/articles" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nopLIB6jLqHoz9LoPK3e" \
-d @- << EOF
{
  "title": "Article title",
  "content": "Article content",
  "published_at": "2025-01-12T17:26:52Z"
}
EOF

# 201 Created
{
  "article": {
    "id": 594821791,
    "title": "Article title",
    "content": "Article content",
    "published_at": "2025-01-12T17:26:52.000Z",
    "read_count": 0
  }
}

error "unauthorized"

error "invalid_params"

params object

▲ ▼

An object containing error messages for all invalid params

Keys string

Values string

Get article

GET http://localhost:3000/api/v1/articles/:article_id

Headers

Authorization string

▲ ▼

format /Bearer [a-zA-Z0-9]{20}/

Params

article_id integer in URL

▲ ▼

only positive

article object

▲ ▼

id integer

▲ ▼

not negative

title string

▲ ▼

not empty

content string

▲ ▼

not empty

published_at string

▲ ▼

When published_at is null it means the article is a draft.
When published_at is a moment in the future it means the article is scheduled to be published.
When published_at is a moment in the past it means the article is published and can be read by everyone.

Value must be a valid date time according to ISO 8601. For example: "2024-12-10T14:21:00Z"

read_count integer

▲ ▼

only positive

Example

curl -XGET "http://localhost:3000/api/v1/articles/594821790" \
-H "Authorization: Bearer WQrIyO81KttVQsKnQvdy"

# 200 OK
{
  "article": {
    "id": 594821790,
    "title": "Title",
    "content": "Content",
    "published_at": "2025-01-12T17:26:52.000Z",
    "read_count": 0
  }
}

error "unauthorized"

Example

curl -XGET "http://localhost:3000/api/v1/articles/594821790" \
-H "Authorization: Bearer non-existing-token"

# 403 Forbidden
{
  "error": "unauthorized"
}

--Empty body--

Example

curl -XGET "http://localhost:3000/api/v1/articles/594821790" \
-H "Authorization: Bearer ts5aca8nsfhfypxLtxW5"

# 404 Not Found
{
}

error "invalid_params"

params object

▲ ▼

An object containing error messages for all invalid params

Keys string

Values string

Update article

PUT http://localhost:3000/api/v1/articles/:article_id

Headers

Authorization string

▲ ▼

format /Bearer [a-zA-Z0-9]{20}/

Params

article_id integer in URL

▲ ▼

only positive

title string

▲ ▼

not empty

content string

▲ ▼

not empty

published_at string

▲ ▼

Value must be a valid date time according to ISO 8601. For example: "2024-12-10T14:21:00Z"

article object

▲ ▼

id integer

▲ ▼

not negative

title string

▲ ▼

not empty

content string

▲ ▼

not empty

published_at string

▲ ▼

When published_at is null it means the article is a draft.
When published_at is a moment in the future it means the article is scheduled to be published.
When published_at is a moment in the past it means the article is published and can be read by everyone.

Value must be a valid date time according to ISO 8601. For example: "2024-12-10T14:21:00Z"

read_count integer

▲ ▼

only positive

Examples (/)

curl -XPUT "http://localhost:3000/api/v1/articles/594821790" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer EtvxCbKWHvI2qJ1oxyVr" \
-d @- << EOF
{
  "title": "Updated Title",
  "content": "Updated Content",
  "published_at": "2025-01-12T17:26:52Z"
}
EOF

# 200 OK
{
  "article": {
    "title": "Updated Title",
    "content": "Updated Content",
    "published_at": "2025-01-12T17:26:52.000Z",
    "id": 594821790,
    "read_count": 0
  }
}

curl -XPUT "http://localhost:3000/api/v1/articles/594821790" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer PoJHPC6nrMPRKoAOaCmS" \
-d @- << EOF
{
  "title": "Title",
  "content": "Content",
  "published_at": null
}
EOF

# 200 OK
{
  "article": {
    "title": "Title",
    "content": "Content",
    "published_at": null,
    "id": 594821790,
    "read_count": 0
  }
}

error "unauthorized"

Example

curl -XPUT "http://localhost:3000/api/v1/articles/594821790" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer non-existing-token" \
-d @- << EOF
{
  "title": "Updated title",
  "content": "Updated content"
}
EOF

# 403 Forbidden
{
  "error": "unauthorized"
}

--Empty body--

Example

curl -XPUT "http://localhost:3000/api/v1/articles/594821790" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ts5aca8nsfhfypxLtxW5" \
-d @- << EOF
{
  "title": "Updated title",
  "content": "Updated content"
}
EOF

# 404 Not Found
{
}

error "invalid_params"

params object

▲ ▼

An object containing error messages for all invalid params

Keys string

Values string

Everything

POST http://localhost:3000/api/v1/everything

This request requires multipart/form-data encoding for file upload

This request uses all available types in the Explicit gem to showcase and test them.

Params

file1 file

▲ ▼

max size: 2 MB

content types: image/jpeg, image/png

string1 string

▲ ▼

not empty

min_length 1

max_length 100

integer1 integer

▲ ▼

min 1

max 100

hash1 object

▲ ▼

Keys string

▲ ▼

not empty

Values array of integer

▲ ▼

A description of the hash values

Items integer

▲ ▼

min 0

max 10

agreement1 boolean

▲ ▼

The following values are accepted:

true "true" "on" "1" 1

big_decimal1 string

▲ ▼

min: 0

max: 100

boolean1 boolean

▲ ▼

The following values are accepted:

true "true" "on" "1" 1 false "false" "off" "0" 0

date1 string

▲ ▼

A date in the format of "YYYY-MM-DD".

date_range1 string

▲ ▼

A date followed by two dots then another date, no spaces: "YYYY-MM-DD..YYYY-MM-DD".

Min range: 1 day

Max range: 30 days

date_time_iso8601_range string

▲ ▼

A range between two date times in the format of "start_date_time..end_date_time" where both date times are valid according to ISO8601. For example: "2024-12-10T14:00:00Z..2024-12-11T15:00:00Z".

Min range: 1 hour

Max range: 24 hours

date_time_iso8601 string

▲ ▼

Value must be a valid date time according to ISO 8601. For example: "2024-12-10T14:21:00Z"

date_time_unix_epoch integer

▲ ▼

Value must be a valid POSIX timestamp. For example: 1733923153 represents "Dec 11 2024 13:19:13"

enum1 string

▲ ▼

The following values are accepted:

"one" "two" "three"

message "ok"

Example

curl -XPOST "http://localhost:3000/api/v1/everything" \
-H "Content-Type: multipart/form-data" \
-F "agreement1=true" \
-F "big_decimal1=10.5" \
-F "boolean1=true" \
-F "date1=2025-01-12" \
-F "date_range1=2025-01-05..2025-01-12" \
-F "date_time_iso8601=2021-01-01T12:00:00Z" \
-F "date_time_iso8601_range=2025-01-12T16:26:53Z..2025-01-12T17:26:53Z" \
-F "date_time_unix_epoch=1609459200" \
-F "enum1=one" \
-F "hash1[key1][]=1" \
-F "hash1[key1][]=2" \
-F "hash1[key1][]=3" \
-F "hash1[key2][]=4" \
-F "hash1[key2][]=5" \
-F "hash1[key2][]=6" \
-F "integer1=42" \
-F "string1=hello#'\"" \
-F file1="@this_is_fine.png"

# 200 OK
{
  "message": "ok"
}

error "invalid_params"

params object

▲ ▼

An object containing error messages for all invalid params

Keys string

Values string