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
|
| | | | | |