Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
readOnly
|
boolean
Default value: false
|
Declares the property as 'read only'. This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be marked as required.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly nickname. The nickname MUST be unique for the model the property belongs to.
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Extends
Parameter
Properties
| Name |
Data Type |
Description |
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
link
|
Link
|
Link to additional external documentation
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
description
|
string
|
A description of the tag
|
name
|
string
Maximum: 50
|
Name of the tag
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "5aaab1d8-4b68-4278-bfec-73107d24eb8a",
"name": "environment",
"description": "API environment related endpoints"
}
|
links
|
array [Link]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
authentications
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
models
|
array [Model]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
readOnly
|
boolean
Default value: false
|
Declares the property as 'read only'. This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be marked as required.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly nickname. The nickname MUST be unique for the model the property belongs to.
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"nickname": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
resources
|
array [Resource]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
tags
|
array [string]
|
List of tags
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
authAdapters
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
responses
|
array [Response]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
examples
|
object
|
A list of example responses
|
parameters
|
array [ResponseParameter]
|
List of response parameters
|
description
|
string
|
Recommended. A brief description of this response
|
message
|
string
|
Individual response message
|
statusCode
|
integer
Default value: 200
|
HTTP status code
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"statusCode": 200,
"message": "Resource created",
"parameters": [
{
"type": "header",
"name": "Location",
"dataType": "string",
"description": "The location (URL) of the newly created resource",
"exampleValues": [
"\/user\/123"
]
},
{
"type": "body",
"dataType": "object",
"ref": "User"
}
]
}
{
"statusCode": 400,
"message": "Bad Request",
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "ClientProblem"
}
]
}
{
"statusCode": 409,
"message": "A user with the provided email address already exist",
"parameters": [
{
"type": "body",
"dataType": "array",
"items": "User",
"description": "The requested email address"
}
]
}
|
parameters
|
array [RequestParameter]
|
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
type
|
string
Allowed values:
- path
- query
- header
- body
- form_data
- cookie
|
The type of the parameter (header, path, query)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"type": "path",
"name": "userId",
"description": "ID of the requested user",
"dataType": "number",
"dataFormat": "integer",
"required": true
}
{
"type": "query",
"name": "token",
"description": "Access token",
"dataType": "string",
"dataFormat": "password",
"minimum": 64,
"maximum": 64,
"required": true,
"exampleValues": [
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ927368asdjhasgd67r812askd82x1"
]
}
{
"type": "header",
"name": "Accept",
"description": "Supported types are 'application\/json' and 'text\/html'",
"dataType": "string",
"dataFormat": "string",
"defaultValue": "application\/json",
"required": false,
"exampleValues": [
"application\/json",
"text\/html"
]
}
{
"type": "body",
"name": "body",
"description": "User model",
"dataType": "object",
"ref": "User"
}
|
description
|
string
|
Description - markdown syntax can be used.
|
summary
|
string
|
Short summary - should not be longer than 150 characters
|
path
|
string
|
Relative URL path - please keep the max URL length of 4096 characters in mind
|
method
|
string
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
status
|
string
Read-only
Allowed values:
- draft
- approval
- feedback_required
- declined
- approved
- canceled
- deprecated
|
Resource status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly resource nickname. The nickname MUST be unique for the logged in user AND the API the resource is assigned to. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided method and path. An error message will be thrown if the generated nickname already exist.
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "b96e182c-10d1-4b6f-ae0e-2da60f1df83a",
"nickname": "health-check",
"revision": 2,
"status": "draft",
"method": "GET",
"path": "\/ping",
"summary": "Health check endpoint",
"responses": [
{
"statusCode": 200,
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "Health",
"description": "Health response model"
}
]
},
{
"statusCode": 500,
"message": "API is unhealthy"
}
],
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
releases
|
array [Release]
|
|
Properties
resources
|
array [ReleaseResource]
|
List of approved resources
|
Properties
revision
|
string
|
Resource revision - if not set the latest revision is used
|
nickname
|
string
|
Resource nickname
|
path
|
string
Read-only
|
Relative URL path
|
method
|
string
Read-only
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
|
endOfLifeDate
|
dateTime
Read-only
|
Timestamp the release reaches end-of-life status - RFC3339
|
endOfLifeNotes
|
string
Read-only
|
End-of-life notes - markdown syntax can be used.
|
deprecatedBy
|
User
Read-only
|
ID of the user who marked the release as deprecated
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
deprecationDate
|
dateTime
Read-only
|
Timestamp the release was marked as deprecated - RFC3339
|
deprecationNotes
|
string
Read-only
|
Deprecation notes - markdown syntax can be used.
|
releasedBy
|
User
Read-only
|
ID of the user who marked the release as released
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
releaseDate
|
dateTime
Read-only
|
Timestamp the release reaches released status - RFC3339
|
releaseNotes
|
string
Read-only
|
Release notes - markdown syntax can be used.
|
status
|
string
Read-only
Default value: unreleased
Allowed values:
- unreleased
- released
- deprecated
- end_of_life
|
The release status is managed automatically by the API. By default the status is unreleased and the release is not publicly visible. The status can be changed using the endpoints POST /release/{userId}/{apiNickname}/{releaseId}/release or POST /release/{userId}/{apiNickname}/{releaseId}/deprecate
|
public
|
boolean
Default value: false
|
Is this release visible for other users? Using this flag makes it possible to share releases even if the API itself is marked private.
|
notes
|
string
|
Internal notes
|
revision
|
long
Read-only
|
API revision the release is based on
|
version
|
string
Pattern: [0-9a-zA-Z.-]*
Maximum: 50
|
Allowed characters are: 0-9, a-z, A-Z, . and -.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "81486795-20d6-40fa-b1ab-f84c9d0ad45c",
"version": "v1.0.1",
"revision": 1,
"notes": "Someone forgot to add the 'status' filter for `GET \/user` method",
"public": true,
"status": "deprecated",
"releaseNotes": "Added 'status' filter",
"releaseDate": "2017-04-17T51:03:44+00:00",
"releasedBy": {
"id": "100001"
},
"deprecationNotes": "Please migrate to `v1.1.0`",
"deprecationDate": "2017-09-13T10:25:40+00:00",
"deprecatedBy": {
"id": "100001"
},
"endOfLifeDate": "2017-11-30T23:59:59+00:00",
"resources": [
{
"nickname": "get-user",
"revision": 2
},
{
"nickname": "get-user-by-id",
"revision": 3
}
]
}
|
environments
|
array [Environment]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
auth
|
Auth
|
|
Properties
value
|
string
|
|
name
|
string
|
Name of the header or query parameter to be used
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
|
public
|
boolean
Default value: true
|
Is this environment visible for other users? Note: Only public environments can be tested.
|
default
|
boolean
Default value: false
|
Is this the default environment? The default environment is used by the quick access links to view or export the specification in one click.
|
description
|
string
|
|
basePath
|
string
Default value: /
|
The base path on which the API is served
|
host
|
string
|
Host name or IP address
|
protocols
|
array [string]
Default value: http
Allowed values:
- http
- https
- ws
- wss
|
List of supported communication protocols (e.g. HTTP, HTTPS, WS, WSS)
|
name
|
string
Maximum: 150
|
|
key
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 100
|
An URL-friendly key for the environment. The key MUST be unique for the given API. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the key is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated key already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"api": {
"id": 90,
"nickname": "billing"
},
"key": "testing",
"name": "Testing",
"protocols": [
"https"
],
"host": "api.test.apitree.org",
"basePath": "\/",
"default": true,
"public": true,
"auth": {
"type": "basic",
"name": "Authentication",
"value": "9173t12uwhwnaksjh"
},
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
contacts
|
array [Contact]
|
List of contact persons
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to external contact information
|
email
|
string
|
Email address of the contact person / organization
|
name
|
string
|
Name of the contact person
|
|
license
|
ApiLicense
|
License of the API
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the license
|
name
|
string
|
Name of the license
|
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
Examples
{
"nickname": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Parameter
Properties
| Name |
Data Type |
Description |
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
link
|
Link
|
Link to additional external documentation
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
description
|
string
|
A description of the tag
|
name
|
string
Maximum: 50
|
Name of the tag
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "5aaab1d8-4b68-4278-bfec-73107d24eb8a",
"name": "environment",
"description": "API environment related endpoints"
}
|
links
|
array [Link]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
authentications
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
models
|
array [Model]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
readOnly
|
boolean
Default value: false
|
Declares the property as 'read only'. This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be marked as required.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly nickname. The nickname MUST be unique for the model the property belongs to.
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"nickname": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
resources
|
array [Resource]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
tags
|
array [string]
|
List of tags
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
authAdapters
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
responses
|
array [Response]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
examples
|
object
|
A list of example responses
|
parameters
|
array [ResponseParameter]
|
List of response parameters
|
description
|
string
|
Recommended. A brief description of this response
|
message
|
string
|
Individual response message
|
statusCode
|
integer
Default value: 200
|
HTTP status code
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"statusCode": 200,
"message": "Resource created",
"parameters": [
{
"type": "header",
"name": "Location",
"dataType": "string",
"description": "The location (URL) of the newly created resource",
"exampleValues": [
"\/user\/123"
]
},
{
"type": "body",
"dataType": "object",
"ref": "User"
}
]
}
{
"statusCode": 400,
"message": "Bad Request",
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "ClientProblem"
}
]
}
{
"statusCode": 409,
"message": "A user with the provided email address already exist",
"parameters": [
{
"type": "body",
"dataType": "array",
"items": "User",
"description": "The requested email address"
}
]
}
|
parameters
|
array [RequestParameter]
|
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
type
|
string
Allowed values:
- path
- query
- header
- body
- form_data
- cookie
|
The type of the parameter (header, path, query)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"type": "path",
"name": "userId",
"description": "ID of the requested user",
"dataType": "number",
"dataFormat": "integer",
"required": true
}
{
"type": "query",
"name": "token",
"description": "Access token",
"dataType": "string",
"dataFormat": "password",
"minimum": 64,
"maximum": 64,
"required": true,
"exampleValues": [
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ927368asdjhasgd67r812askd82x1"
]
}
{
"type": "header",
"name": "Accept",
"description": "Supported types are 'application\/json' and 'text\/html'",
"dataType": "string",
"dataFormat": "string",
"defaultValue": "application\/json",
"required": false,
"exampleValues": [
"application\/json",
"text\/html"
]
}
{
"type": "body",
"name": "body",
"description": "User model",
"dataType": "object",
"ref": "User"
}
|
description
|
string
|
Description - markdown syntax can be used.
|
summary
|
string
|
Short summary - should not be longer than 150 characters
|
path
|
string
|
Relative URL path - please keep the max URL length of 4096 characters in mind
|
method
|
string
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
status
|
string
Read-only
Allowed values:
- draft
- approval
- feedback_required
- declined
- approved
- canceled
- deprecated
|
Resource status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly resource nickname. The nickname MUST be unique for the logged in user AND the API the resource is assigned to. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided method and path. An error message will be thrown if the generated nickname already exist.
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "b96e182c-10d1-4b6f-ae0e-2da60f1df83a",
"nickname": "health-check",
"revision": 2,
"status": "draft",
"method": "GET",
"path": "\/ping",
"summary": "Health check endpoint",
"responses": [
{
"statusCode": 200,
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "Health",
"description": "Health response model"
}
]
},
{
"statusCode": 500,
"message": "API is unhealthy"
}
],
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
releases
|
array [Release]
|
|
Properties
resources
|
array [ReleaseResource]
|
List of approved resources
|
Properties
revision
|
string
|
Resource revision - if not set the latest revision is used
|
nickname
|
string
|
Resource nickname
|
path
|
string
Read-only
|
Relative URL path
|
method
|
string
Read-only
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
|
endOfLifeDate
|
dateTime
Read-only
|
Timestamp the release reaches end-of-life status - RFC3339
|
endOfLifeNotes
|
string
Read-only
|
End-of-life notes - markdown syntax can be used.
|
deprecatedBy
|
User
Read-only
|
ID of the user who marked the release as deprecated
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
deprecationDate
|
dateTime
Read-only
|
Timestamp the release was marked as deprecated - RFC3339
|
deprecationNotes
|
string
Read-only
|
Deprecation notes - markdown syntax can be used.
|
releasedBy
|
User
Read-only
|
ID of the user who marked the release as released
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
releaseDate
|
dateTime
Read-only
|
Timestamp the release reaches released status - RFC3339
|
releaseNotes
|
string
Read-only
|
Release notes - markdown syntax can be used.
|
status
|
string
Read-only
Default value: unreleased
Allowed values:
- unreleased
- released
- deprecated
- end_of_life
|
The release status is managed automatically by the API. By default the status is unreleased and the release is not publicly visible. The status can be changed using the endpoints POST /release/{userId}/{apiNickname}/{releaseId}/release or POST /release/{userId}/{apiNickname}/{releaseId}/deprecate
|
public
|
boolean
Default value: false
|
Is this release visible for other users? Using this flag makes it possible to share releases even if the API itself is marked private.
|
notes
|
string
|
Internal notes
|
revision
|
long
Read-only
|
API revision the release is based on
|
version
|
string
Pattern: [0-9a-zA-Z.-]*
Maximum: 50
|
Allowed characters are: 0-9, a-z, A-Z, . and -.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "81486795-20d6-40fa-b1ab-f84c9d0ad45c",
"version": "v1.0.1",
"revision": 1,
"notes": "Someone forgot to add the 'status' filter for `GET \/user` method",
"public": true,
"status": "deprecated",
"releaseNotes": "Added 'status' filter",
"releaseDate": "2017-04-17T51:03:44+00:00",
"releasedBy": {
"id": "100001"
},
"deprecationNotes": "Please migrate to `v1.1.0`",
"deprecationDate": "2017-09-13T10:25:40+00:00",
"deprecatedBy": {
"id": "100001"
},
"endOfLifeDate": "2017-11-30T23:59:59+00:00",
"resources": [
{
"nickname": "get-user",
"revision": 2
},
{
"nickname": "get-user-by-id",
"revision": 3
}
]
}
|
environments
|
array [Environment]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
auth
|
Auth
|
|
Properties
value
|
string
|
|
name
|
string
|
Name of the header or query parameter to be used
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
|
public
|
boolean
Default value: true
|
Is this environment visible for other users? Note: Only public environments can be tested.
|
default
|
boolean
Default value: false
|
Is this the default environment? The default environment is used by the quick access links to view or export the specification in one click.
|
description
|
string
|
|
basePath
|
string
Default value: /
|
The base path on which the API is served
|
host
|
string
|
Host name or IP address
|
protocols
|
array [string]
Default value: http
Allowed values:
- http
- https
- ws
- wss
|
List of supported communication protocols (e.g. HTTP, HTTPS, WS, WSS)
|
name
|
string
Maximum: 150
|
|
key
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 100
|
An URL-friendly key for the environment. The key MUST be unique for the given API. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the key is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated key already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"api": {
"id": 90,
"nickname": "billing"
},
"key": "testing",
"name": "Testing",
"protocols": [
"https"
],
"host": "api.test.apitree.org",
"basePath": "\/",
"default": true,
"public": true,
"auth": {
"type": "basic",
"name": "Authentication",
"value": "9173t12uwhwnaksjh"
},
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
contacts
|
array [Contact]
|
List of contact persons
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to external contact information
|
email
|
string
|
Email address of the contact person / organization
|
name
|
string
|
Name of the contact person
|
|
license
|
ApiLicense
|
License of the API
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the license
|
name
|
string
|
Name of the license
|
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Parameter
Properties
| Name |
Data Type |
Description |
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
link
|
Link
|
Link to additional external documentation
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
description
|
string
|
A description of the tag
|
name
|
string
Maximum: 50
|
Name of the tag
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "5aaab1d8-4b68-4278-bfec-73107d24eb8a",
"name": "environment",
"description": "API environment related endpoints"
}
|
links
|
array [Link]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
authentications
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
models
|
array [Model]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
readOnly
|
boolean
Default value: false
|
Declares the property as 'read only'. This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be marked as required.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly nickname. The nickname MUST be unique for the model the property belongs to.
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"nickname": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
resources
|
array [Resource]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
tags
|
array [string]
|
List of tags
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
authAdapters
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
responses
|
array [Response]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
examples
|
object
|
A list of example responses
|
parameters
|
array [ResponseParameter]
|
List of response parameters
|
description
|
string
|
Recommended. A brief description of this response
|
message
|
string
|
Individual response message
|
statusCode
|
integer
Default value: 200
|
HTTP status code
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"statusCode": 200,
"message": "Resource created",
"parameters": [
{
"type": "header",
"name": "Location",
"dataType": "string",
"description": "The location (URL) of the newly created resource",
"exampleValues": [
"\/user\/123"
]
},
{
"type": "body",
"dataType": "object",
"ref": "User"
}
]
}
{
"statusCode": 400,
"message": "Bad Request",
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "ClientProblem"
}
]
}
{
"statusCode": 409,
"message": "A user with the provided email address already exist",
"parameters": [
{
"type": "body",
"dataType": "array",
"items": "User",
"description": "The requested email address"
}
]
}
|
parameters
|
array [RequestParameter]
|
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
type
|
string
Allowed values:
- path
- query
- header
- body
- form_data
- cookie
|
The type of the parameter (header, path, query)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"type": "path",
"name": "userId",
"description": "ID of the requested user",
"dataType": "number",
"dataFormat": "integer",
"required": true
}
{
"type": "query",
"name": "token",
"description": "Access token",
"dataType": "string",
"dataFormat": "password",
"minimum": 64,
"maximum": 64,
"required": true,
"exampleValues": [
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ927368asdjhasgd67r812askd82x1"
]
}
{
"type": "header",
"name": "Accept",
"description": "Supported types are 'application\/json' and 'text\/html'",
"dataType": "string",
"dataFormat": "string",
"defaultValue": "application\/json",
"required": false,
"exampleValues": [
"application\/json",
"text\/html"
]
}
{
"type": "body",
"name": "body",
"description": "User model",
"dataType": "object",
"ref": "User"
}
|
description
|
string
|
Description - markdown syntax can be used.
|
summary
|
string
|
Short summary - should not be longer than 150 characters
|
path
|
string
|
Relative URL path - please keep the max URL length of 4096 characters in mind
|
method
|
string
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
status
|
string
Read-only
Allowed values:
- draft
- approval
- feedback_required
- declined
- approved
- canceled
- deprecated
|
Resource status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly resource nickname. The nickname MUST be unique for the logged in user AND the API the resource is assigned to. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided method and path. An error message will be thrown if the generated nickname already exist.
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "b96e182c-10d1-4b6f-ae0e-2da60f1df83a",
"nickname": "health-check",
"revision": 2,
"status": "draft",
"method": "GET",
"path": "\/ping",
"summary": "Health check endpoint",
"responses": [
{
"statusCode": 200,
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "Health",
"description": "Health response model"
}
]
},
{
"statusCode": 500,
"message": "API is unhealthy"
}
],
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
releases
|
array [Release]
|
|
Properties
resources
|
array [ReleaseResource]
|
List of approved resources
|
Properties
revision
|
string
|
Resource revision - if not set the latest revision is used
|
nickname
|
string
|
Resource nickname
|
path
|
string
Read-only
|
Relative URL path
|
method
|
string
Read-only
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
|
endOfLifeDate
|
dateTime
Read-only
|
Timestamp the release reaches end-of-life status - RFC3339
|
endOfLifeNotes
|
string
Read-only
|
End-of-life notes - markdown syntax can be used.
|
deprecatedBy
|
User
Read-only
|
ID of the user who marked the release as deprecated
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
deprecationDate
|
dateTime
Read-only
|
Timestamp the release was marked as deprecated - RFC3339
|
deprecationNotes
|
string
Read-only
|
Deprecation notes - markdown syntax can be used.
|
releasedBy
|
User
Read-only
|
ID of the user who marked the release as released
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
releaseDate
|
dateTime
Read-only
|
Timestamp the release reaches released status - RFC3339
|
releaseNotes
|
string
Read-only
|
Release notes - markdown syntax can be used.
|
status
|
string
Read-only
Default value: unreleased
Allowed values:
- unreleased
- released
- deprecated
- end_of_life
|
The release status is managed automatically by the API. By default the status is unreleased and the release is not publicly visible. The status can be changed using the endpoints POST /release/{userId}/{apiNickname}/{releaseId}/release or POST /release/{userId}/{apiNickname}/{releaseId}/deprecate
|
public
|
boolean
Default value: false
|
Is this release visible for other users? Using this flag makes it possible to share releases even if the API itself is marked private.
|
notes
|
string
|
Internal notes
|
revision
|
long
Read-only
|
API revision the release is based on
|
version
|
string
Pattern: [0-9a-zA-Z.-]*
Maximum: 50
|
Allowed characters are: 0-9, a-z, A-Z, . and -.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "81486795-20d6-40fa-b1ab-f84c9d0ad45c",
"version": "v1.0.1",
"revision": 1,
"notes": "Someone forgot to add the 'status' filter for `GET \/user` method",
"public": true,
"status": "deprecated",
"releaseNotes": "Added 'status' filter",
"releaseDate": "2017-04-17T51:03:44+00:00",
"releasedBy": {
"id": "100001"
},
"deprecationNotes": "Please migrate to `v1.1.0`",
"deprecationDate": "2017-09-13T10:25:40+00:00",
"deprecatedBy": {
"id": "100001"
},
"endOfLifeDate": "2017-11-30T23:59:59+00:00",
"resources": [
{
"nickname": "get-user",
"revision": 2
},
{
"nickname": "get-user-by-id",
"revision": 3
}
]
}
|
environments
|
array [Environment]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
auth
|
Auth
|
|
Properties
value
|
string
|
|
name
|
string
|
Name of the header or query parameter to be used
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
|
public
|
boolean
Default value: true
|
Is this environment visible for other users? Note: Only public environments can be tested.
|
default
|
boolean
Default value: false
|
Is this the default environment? The default environment is used by the quick access links to view or export the specification in one click.
|
description
|
string
|
|
basePath
|
string
Default value: /
|
The base path on which the API is served
|
host
|
string
|
Host name or IP address
|
protocols
|
array [string]
Default value: http
Allowed values:
- http
- https
- ws
- wss
|
List of supported communication protocols (e.g. HTTP, HTTPS, WS, WSS)
|
name
|
string
Maximum: 150
|
|
key
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 100
|
An URL-friendly key for the environment. The key MUST be unique for the given API. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the key is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated key already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"api": {
"id": 90,
"nickname": "billing"
},
"key": "testing",
"name": "Testing",
"protocols": [
"https"
],
"host": "api.test.apitree.org",
"basePath": "\/",
"default": true,
"public": true,
"auth": {
"type": "basic",
"name": "Authentication",
"value": "9173t12uwhwnaksjh"
},
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
contacts
|
array [Contact]
|
List of contact persons
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to external contact information
|
email
|
string
|
Email address of the contact person / organization
|
name
|
string
|
Name of the contact person
|
|
license
|
ApiLicense
|
License of the API
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the license
|
name
|
string
|
Name of the license
|
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
tags
|
array [string]
|
List of tags
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
authAdapters
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
responses
|
array [Response]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
examples
|
object
|
A list of example responses
|
parameters
|
array [ResponseParameter]
|
List of response parameters
|
description
|
string
|
Recommended. A brief description of this response
|
message
|
string
|
Individual response message
|
statusCode
|
integer
Default value: 200
|
HTTP status code
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"statusCode": 200,
"message": "Resource created",
"parameters": [
{
"type": "header",
"name": "Location",
"dataType": "string",
"description": "The location (URL) of the newly created resource",
"exampleValues": [
"\/user\/123"
]
},
{
"type": "body",
"dataType": "object",
"ref": "User"
}
]
}
{
"statusCode": 400,
"message": "Bad Request",
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "ClientProblem"
}
]
}
{
"statusCode": 409,
"message": "A user with the provided email address already exist",
"parameters": [
{
"type": "body",
"dataType": "array",
"items": "User",
"description": "The requested email address"
}
]
}
|
parameters
|
array [RequestParameter]
|
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
type
|
string
Allowed values:
- path
- query
- header
- body
- form_data
- cookie
|
The type of the parameter (header, path, query)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
api
|
Api
Read-only
|
|
Extends
Parameter
Properties
| Name |
Data Type |
Description |
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
link
|
Link
|
Link to additional external documentation
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
description
|
string
|
A description of the tag
|
name
|
string
Maximum: 50
|
Name of the tag
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "5aaab1d8-4b68-4278-bfec-73107d24eb8a",
"name": "environment",
"description": "API environment related endpoints"
}
|
links
|
array [Link]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
url
|
string
|
URL pointing to the target link
|
description
|
string
|
A description of the link
|
name
|
string
|
Name of the link
|
category
|
string
Default value: doc
|
Category of the link - e.g. doc, sdk, repository, terms_of_service
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3167f1b0-b5dd-4a89-9bcb-fb3514bd19fd",
"category": "terms_of_service",
"url": "https:\/\/www.apitree.com\/terms"
}
|
authentications
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
models
|
array [Model]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
readOnly
|
boolean
Default value: false
|
Declares the property as 'read only'. This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be marked as required.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly nickname. The nickname MUST be unique for the model the property belongs to.
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"nickname": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
properties
|
array [ModelProperty]
|
List of domain model properties
|
extends
|
array [string]
|
The name of the models which extends the current model
|
parent
|
Model
|
Not implemented!
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
description
|
string
|
Recommended. A brief description of this parameter
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
status
|
string
Read-only
Allowed values:
- draft
- approved
|
Domain-model status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly domain-model nickname. The nickname MUST be unique for the current API. The nickname cannot be changed. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided name. An error message will be thrown if the generated nickname already exist.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
name
|
string
Maximum: 150
|
Name of the API
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly API nickname. The nickname MUST be unique for the logged in user. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided label. An error message will be thrown if the generated nickname already exist.
|
user
|
User
Read-only
|
|
revision
|
long
Read-only
|
Revision
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "3c2aca15-24d8-40ff-b805-b61c33312770",
"revision": 1,
"user": {
"id": "100001"
},
"type": "public",
"nickname": "billing",
"name": "Payment API",
"description": "Payment API for invoicing and accounting",
"categories": [
"billing",
"payment"
],
"license": {
"name": "Proprietary"
},
"contacts": [
{
"name": "ApiTree",
"email": "info@apitree.com"
}
],
"links": [
{
"category": "terms_of_service\"",
"name": "https:\/\/www.apitree.com\/terms"
}
],
"tagDefinitions": [
{
"name": "billing",
"description": "Billing (payment) related endpoints"
}
],
"metadata": [
{
"key": "swagger_version",
"value": "2.0"
},
{
"key": "repository_provider",
"value": "github"
},
{
"key": "repository_url",
"value": "https:\/\/github.com\/apitree\/billing-api"
}
],
"creationDate": "2017-10-17T10:18:48+02:00"
}
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
Extends
Examples
{
"id": "ee8b5c29-e4dc-46d5-9eaf-03d8525aefdf",
"nickname": "user",
"revision": 1,
"status": "draft",
"name": "User",
"description": "User model",
"properties": [
{
"key": "userId",
"name": "User-ID",
"description": "Internal unique user identifier (auto-increment value)",
"dataType": "integer",
"minimum": 1,
"exampleValues": [
8723
],
"required": true
}
],
"creationDate": "2019-10-18T10:17:35+12:00"
}
|
resources
|
array [Resource]
|
|
Properties
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
tags
|
array [string]
|
List of tags
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
Properties
value
|
string
|
|
key
|
string
|
Must be unique
|
|
authAdapters
|
array [AuthAdapter]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
oauthTokenUrl
|
string
|
OAuth token URL (required for 'password', 'application' and 'accessCode' flow)
|
oauthAuthorizationUrl
|
string
|
OAuth authorization URL (required for 'implicit' and 'accessCode' flow)
|
oauthScopes
|
object
|
List of available OAuth scopes
|
oauthFlow
|
string
Allowed values:
- implicit
- password
- clientCredentials
- authorizationCode
|
OAuth flow ('application' (client), 'password', 'accessCode', 'implicit')
|
description
|
string
|
|
type
|
string
Allowed values:
- api_key
- basic
- bearer
- digest
- jwt
- oauth
- oauth2
|
List of supported authentication mechanisms
|
name
|
string
Maximum: 150
|
Name of the header or query parameter to be used
|
location
|
string
Allowed values:
- header
- query
|
Location of the authentication adapter
|
key
|
string
Maximum: 100
|
Unique auth-adapter key
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "481ff4a5-3ef7-528e-80f6-d4d1b9759afa",
"key": "jwt",
"name": "Authentication",
"type": "jwt"
}
|
responses
|
array [Response]
|
|
Properties
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
examples
|
object
|
A list of example responses
|
parameters
|
array [ResponseParameter]
|
List of response parameters
|
description
|
string
|
Recommended. A brief description of this response
|
message
|
string
|
Individual response message
|
statusCode
|
integer
Default value: 200
|
HTTP status code
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"statusCode": 200,
"message": "Resource created",
"parameters": [
{
"type": "header",
"name": "Location",
"dataType": "string",
"description": "The location (URL) of the newly created resource",
"exampleValues": [
"\/user\/123"
]
},
{
"type": "body",
"dataType": "object",
"ref": "User"
}
]
}
{
"statusCode": 400,
"message": "Bad Request",
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "ClientProblem"
}
]
}
{
"statusCode": 409,
"message": "A user with the provided email address already exist",
"parameters": [
{
"type": "body",
"dataType": "array",
"items": "User",
"description": "The requested email address"
}
]
}
|
parameters
|
array [RequestParameter]
|
|
Properties
required
|
boolean
Default value: false
|
Determines whether this parameter is mandatory
|
name
|
string
Maximum: 100
|
The unique name for the parameter (case sensitive)
|
type
|
string
Allowed values:
- path
- query
- header
- body
- form_data
- cookie
|
The type of the parameter (header, path, query)
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
deprecated
|
boolean
Default value: false
|
Specifies that a parameter is deprecated and SHOULD be transitioned out of usage
|
exampleValues
|
array [object]
|
List of example values
|
defaultValue
|
string
|
Default value
|
multipleOf
|
float
|
The number is valid if the result of the division is an integer - only allowed for dataType=number
|
uniqueItems
|
boolean
|
Defines if all of the items of an array must be unique - only allowed for dataType=array
|
allowedValues
|
object
|
List of allowed values - only allowed for dataType=array|enum|file
|
items
|
string
|
Contains an ID of a Model object which describes the items in the array
|
pattern
|
string
|
Regex pattern - only allowed for dataType=string
|
exclusiveMaximum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
maximum
|
float
|
Only allowed for dataType=array|number|string:
- Array: Maximum amount of items the array may contain
- Number: Maximum valid inclusive value
- String: Maximum valid length of a string
|
exclusiveMinimum
|
boolean
Default value: false
|
Defines if the value must be strictly greater than the defined minimum value - only allowed for dataType=number
|
minimum
|
float
|
Minimum allowed value
|
ref
|
string
|
ID of the existing Model object
|
dataFormat
|
string
Allowed values:
- byte
- short
- integer
- long
- float
- double
- string
- binary
- null
- hostname
- uri
- ipv4
- ipv6
- date
- time
- dateTime
- email
- password
- uuid
|
The data-format must match to the choosen data-type.
| Data-Type |
Data-Format |
Notes |
array |
|
Collection of elements |
boolean |
|
true or false |
enum |
|
Fixed list of possible values |
file |
|
Binary data |
number |
byte |
Signed or unsigned 8 bits |
number |
short |
Signed or unsigned 16 bits |
number |
integer |
Signed or unsigned 32 bits |
number |
long |
Signed or unsigned 64 bits |
number |
float |
Single precision - 32 bits |
number |
double |
Double precision - 64 bits |
string |
string |
Sequence of characters |
string |
binary |
Sequence of octets |
string |
null |
null character |
string |
hostname |
Host name as defined by RFC 1034, section 3.1 |
string |
uri |
URI according to RFC3986 |
string |
ipv4 |
Address according to the "dotted-quad" ABNF syntax |
string |
ipv6 |
Address as defined in RFC 2373 |
string |
date |
Format is YYYY-MM-DD and ranges from -4712-01-01 (January 1, 4712 BC) to 9999-12-31 (December 31, 9999 AD) |
string |
time |
Format is HH:MI:SS and ranges from 00:00:00 (midnight) to 23:59:59 (11:59:59 pm) |
string |
dateTime |
Format of a 'dateTime' value is YYYY-MM-DD HH:MI:SS which is a combination of 'date' and 'time' |
string |
email |
Internet email address as defined by RFC 5322, section 3.4.1 |
string |
password |
Used to hint UIs the input needs to be obscured |
string |
uuid |
Universally Unique Identifier (UUID) as defined by RFC 4122 |
object |
|
Domain model object |
|
dataType
|
string
|
The data-type. Allowed are the following types: array, binary, boolean, enum, number, string, object, byte, short, integer, long, float, double, null, hostname, uri, ipv4, ipv6, date, time, dateTime, email, password. However custom data-types are also possible, but not recommended.
|
description
|
string
|
Recommended. A brief description of this parameter
|
api
|
Api
Read-only
|
|
Extends
Examples
{
"type": "path",
"name": "userId",
"description": "ID of the requested user",
"dataType": "number",
"dataFormat": "integer",
"required": true
}
{
"type": "query",
"name": "token",
"description": "Access token",
"dataType": "string",
"dataFormat": "password",
"minimum": 64,
"maximum": 64,
"required": true,
"exampleValues": [
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ927368asdjhasgd67r812askd82x1"
]
}
{
"type": "header",
"name": "Accept",
"description": "Supported types are 'application\/json' and 'text\/html'",
"dataType": "string",
"dataFormat": "string",
"defaultValue": "application\/json",
"required": false,
"exampleValues": [
"application\/json",
"text\/html"
]
}
{
"type": "body",
"name": "body",
"description": "User model",
"dataType": "object",
"ref": "User"
}
|
description
|
string
|
Description - markdown syntax can be used.
|
summary
|
string
|
Short summary - should not be longer than 150 characters
|
path
|
string
|
Relative URL path - please keep the max URL length of 4096 characters in mind
|
method
|
string
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
status
|
string
Read-only
Allowed values:
- draft
- approval
- feedback_required
- declined
- approved
- canceled
- deprecated
|
Resource status
|
revision
|
integer
Read-only
Minimum: 1
|
Number of the revision. Will automatically increase depending on the status.
|
nickname
|
string
Pattern: [0-9a-zA-Z-_]*
Maximum: 150
|
An URL-friendly resource nickname. The nickname MUST be unique for the logged in user AND the API the resource is assigned to. Allowed characters are: 0-9, a-z, A-Z, - and _. In case the nickname is not provided the API will automatically generate one from the provided method and path. An error message will be thrown if the generated nickname already exist.
|
id
|
string
Read-only
|
Unique identifier (UUID version 4)
|
Examples
{
"id": "b96e182c-10d1-4b6f-ae0e-2da60f1df83a",
"nickname": "health-check",
"revision": 2,
"status": "draft",
"method": "GET",
"path": "\/ping",
"summary": "Health check endpoint",
"responses": [
{
"statusCode": 200,
"parameters": [
{
"type": "body",
"dataType": "object",
"ref": "Health",
"description": "Health response model"
}
]
},
{
"statusCode": 500,
"message": "API is unhealthy"
}
],
"creationDate": "2019-10-17T10:18:48+02:00"
}
|
releases
|
array [Release]
|
|
Properties
resources
|
array [ReleaseResource]
|
List of approved resources
|
Properties
revision
|
string
|
Resource revision - if not set the latest revision is used
|
nickname
|
string
|
Resource nickname
|
path
|
string
Read-only
|
Relative URL path
|
method
|
string
Read-only
Allowed values:
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
|
HTTP method
|
|
endOfLifeDate
|
dateTime
Read-only
|
Timestamp the release reaches end-of-life status - RFC3339
|
endOfLifeNotes
|
string
Read-only
|
End-of-life notes - markdown syntax can be used.
|
deprecatedBy
|
User
Read-only
|
ID of the user who marked the release as deprecated
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
deprecationDate
|
dateTime
Read-only
|
Timestamp the release was marked as deprecated - RFC3339
|
deprecationNotes
|
string
Read-only
|
Deprecation notes - markdown syntax can be used.
|
releasedBy
|
User
Read-only
|
ID of the user who marked the release as released
|
Properties
nickname
|
string
Read-only
|
User nickname - it might happen that the nickname changed in the meanwhile
|
id
|
string
Read-only
|
Unique user ID
|
Examples
{
"id": "100007",
"username": "john-doe"
}
|
releaseDate
|
dateTime
Read-only
|
Timestamp the release reaches released status - RFC3339
|
releaseNotes
|
string
Read-only
|
Release notes - markdown syntax can be used.
|
status
|
string
Read-only
Default value: unreleased
Allowed values:
- unreleased
- released
- deprecated
- end_of_life
|
The release status is managed automatically by the API. By default the status is unreleased and the release is not publicly visible. The status can be changed using the endpoints POST /release/{userId}/{apiNickname}/{releaseId}/release or POST /release/{userId}/{apiNickname}/{releaseId}/deprecate
|
public
|
boolean
Default value: false
|
Is this release visible for other users? Using this flag makes it possible to share releases even if the API itself is marked private.
|
notes
|
string
|
Internal notes
|
revision
|
long
Read-only
|
API revision the release is based on
|
version
|
string
Pattern: [0-9a-zA-Z.-]*
Maximum: 50
|
Allowed characters are: 0-9, a-z, A-Z, . and -.
|
api
|
Api
Read-only
|
|
Properties
tagDefinitions
|
array [TagDefinition]
|
|
links
|
array [Link]
|
|
authentications
|
array [AuthAdapter]
|
|
models
|
array [Model]
|
|
resources
|
array [Resource]
|
|
releases
|
array [Release]
|
|
environments
|
array [Environment]
|
|
creationDate
|
dateTime
Read-only
|
Date of creation - RFC3339
|
categories
|
array [string]
|
List of categories
|
metadata
|
array [Metadata]
|
Metadata as key-value pairs
|
contacts
|
array [Contact]
|
List of contact persons
|
license
|
ApiLicense
|
License of the API
|
description
|
string
|
A description of the API
|
type
|
string
Default value: private
Allowed values:
- example
- public
- private
|
Visibility of the API
|
| | | | | |
