OpenAPI example logo
API docs by Redocly

Example API (1.0.0)

Download OpenAPI specification:Download

Contact our support: contact@example.com URL: http://example.com/contact License: Apache 2.0 Terms of Service

This is an example API to demonstrate features of the OpenAPI specification.

Find out how to create a GitHub repo for your OpenAPI definition.

Introduction

This API definition is intended to to be a good starting point for describing your API in OpenAPI/Swagger format. It also demonstrates features of the create-openapi-repo tool and the Redoc documentation engine. Beyond the standard OpenAPI syntax, we use a few vendor extensions.

OpenAPI Specification

The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.

User

Example actions on user accounts.

Get user by name

Example description of the operation. You can use markdown here.

Authorizations:
main_authapi_key
path Parameters
username
required
string
Example: John78

The username for which you want to retrieve the data.

query Parameters
pretty_print
boolean
Default: false

Choose whether to pretty print the response. This option is disabled by default.

with_email
boolean
Default: true

Use this parameter to filter users without email. By default, only users with email are displayed.

userid
integer <int64>
Deprecated

ID of the user. This is an example of a deprecated parameter.

Responses

Response samples

Content type
application/json
{
  • "username": "user1",
  • "email": "user@example.com"
}

Update user data

This operation allows users to update the information in their own profile. The update can only be performed by the logged in user.

Authorizations:
main_auth
path Parameters
username
required
string

The name of the user profile to be updated.

query Parameters
pretty_print
boolean
Default: false

Choose whether to pretty print the response. This option is disabled by default.

Request Body schema:
required

Updated user object

username
required
string [ 4 .. 32 ] characters /(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])/

The username associated with the user profile.

firstName
string non-empty

User's first name.

lastName
string non-empty

User's last name.

email
string <email> (Email)

User's email address.

object

Example object to show an expanded schema.

phone
string <= 32 characters /^\+(?:[0-9]-?){6,14}[0-9]$/

User's phone number. Must be provided in international format.

profileUrls
Array of strings <url> <= 10 items [ items <url > ]

The list of URLs to user's social media profiles. You must provide the URLs with the scheme (http or https).

recursiveProperty
object Recursive
status
required
Array of strings non-empty
Items Enum: "active" "banned" "inactive"

Status of the user account.

userType
required
string
adminDept
required
string
Default: "all"
Enum: "all" "finance" "hiring" "development" "support" "contractors"

One or more departments which the admin user controls.

Responses

Request samples

Content type
Example
{
  • "username": "John78",
  • "firstName": "Bunny",
  • "lastName": "Rabbit",
  • "email": "bunny.rabbit@example.com",
  • "exampleObject": {
    },
  • "phone": "+4-0800-555-0110",
  • "profileUrls": [],
  • "recursiveProperty": { },
  • "status": [
    ],
  • "userType": "admin",
  • "adminDept": "finance"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "message": "OK"
}

Info

Example operations for retrieving information.

New user webhook Webhook

Information about a new user in the system.

Authorizations:
api_key
Request Body schema: application/json
username
required
string [ 4 .. 32 ] characters /(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])/

The username associated with the user profile.

firstName
string non-empty

User's first name.

lastName
string non-empty

User's last name.

email
string <email> (Email)

User's email address.

object

Example object to show an expanded schema.

phone
string <= 32 characters /^\+(?:[0-9]-?){6,14}[0-9]$/

User's phone number. Must be provided in international format.

profileUrls
Array of strings <url> <= 10 items [ items <url > ]

The list of URLs to user's social media profiles. You must provide the URLs with the scheme (http or https).

recursiveProperty
object Recursive
status
required
Array of strings non-empty
Items Enum: "active" "banned" "inactive"

Status of the user account.

userid
integer <int64>

Unique ID of the user.

Example of external documentation link
userType
required
string
adminDept
required
string
Default: "all"
Enum: "all" "finance" "hiring" "development" "support" "contractors"

One or more departments which the admin user controls.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "John78",
  • "firstName": "Bunny",
  • "lastName": "Rabbit",
  • "email": "bunny.rabbit@example.com",
  • "exampleObject": {
    },
  • "phone": "+4-0800-555-0110",
  • "profileUrls": [],
  • "recursiveProperty": { },
  • "status": [
    ],
  • "userid": 27,
  • "userType": "admin",
  • "adminDept": "finance"
}

Echo

Example echo operations.

Echo test

This endpoint returns the exact message you've sent to it. You can use it for testing purposes.

Authorizations:
api_keybasic_auth
Request Body schema:
required

Example Echo payload. When the response is received, its contents should match the contents from the payload.

string

Responses

Request samples

Content type
"Hello world!"

Response samples

Content type
"Hello world!"

Admin

Example operations reserved for administrators.

Delete a user

This operation deletes all data associated with the requested username. Only administrators can perform this operation.

Authorizations:
main_authapi_key
path Parameters
username
required
string
Example: John78

The name of the user profile to be deleted.

query Parameters
pretty_print
boolean
Default: false

Choose whether to pretty print the response. This option is disabled by default.

header Parameters
api_key
string
Example: Bearer <TOKEN>

Responses

Create a new user

This operation creates a new user profile. Only administrators can create user profiles.

Authorizations:
main_auth
cookie Parameters
cookieParam
required
integer <int64>

Example cookie parameter.

header Parameters
Accept-Language
string
Default: en-GB
Example: en-US

The language you prefer for messages. Supported values are en-AU, en-CA, en-GB, en-US.

Request Body schema:
required

User profile to be added to the database.

username
required
string [ 4 .. 32 ] characters /(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])/

The username associated with the user profile.

firstName
string non-empty

User's first name.

lastName
string non-empty

User's last name.

email
string <email> (Email)

User's email address.

object

Example object to show an expanded schema.

phone
string <= 32 characters /^\+(?:[0-9]-?){6,14}[0-9]$/

User's phone number. Must be provided in international format.

profileUrls
Array of strings <url> <= 10 items [ items <url > ]

The list of URLs to user's social media profiles. You must provide the URLs with the scheme (http or https).

recursiveProperty
object Recursive
status
required
Array of strings non-empty
Items Enum: "active" "banned" "inactive"

Status of the user account.

userType
required
string
adminDept
required
string
Default: "all"
Enum: "all" "finance" "hiring" "development" "support" "contractors"

One or more departments which the admin user controls.

Responses

Request samples

Content type
Example
{
  • "username": "John78",
  • "firstName": "Bunny",
  • "lastName": "Rabbit",
  • "email": "bunny.rabbit@example.com",
  • "exampleObject": {
    },
  • "phone": "+4-0800-555-0110",
  • "profileUrls": [],
  • "recursiveProperty": { },
  • "status": [
    ],
  • "userType": "admin",
  • "adminDept": "finance"
}

List users by status Deprecated

This operation lets you list users by their status. Multiple status values can be provided in a single request by using comma-separated strings. Only administrators can use this operation.

This is an example of a deprecated operation.

Authorizations:
main_auth
query Parameters
status
required
Array of strings [ 1 .. 3 ] items unique
Items Enum: "active" "banned" "inactive"

One or more user status values by which to look up user accounts.

Responses

Response samples

Content type
[
  • {
    }
]