The PingOne /environments/{{envID}}/apiServers
endpoint provides operations to create, read, update, and delete API servers in PingOne. An API server models a customer’s APIs, which are then protected by the PingOne API access management service.
Property | Type? | Required? | Mutable? | Description |
---|---|---|---|---|
authorizationServer |
Object | Required | Mutable | A container object for properties related to the authorization server that will issue access tokens used to access the APIs. |
authorizationServer.resource |
Relationship | Required | Mutable | The resource defines the characteristics of the OAuth 2.0 access tokens used to get access to the APIs on the API server such as the audience and scopes. |
authorizationServer.resource.id |
UUID | Required | Mutable | A string that specifies the UUID of the custom PingOne resource. This property must identify a PingOne resource with a type property value of CUSTOM . |
baseURLs |
Array | Required | Mutable | An array of string that specifies the possible base URLs that an end-user will use to access the APIs hosted on the customer’s API server. Multiple base URLs may be specified to support cases where the same API may be available from multiple URLs (for example, from a user-friendly domain URL and an internal domain URL). Base URLs must be valid absolute URLs with the https or http scheme. If the path component is non-empty, it must not end in a trailing slash. The path must not contain empty backslash, dot, or double-dot segments. It must not have a query or fragment present, and the host portion of the authority must be a DNS hostname or valid IP (IPv4 or IPv6). The length must be less than or equal to 256 characters. |
id |
UUID | Read-only | A string that specifies the resource’s unique identifier. | |
name |
String | Required | Mutable | A string that specifies the API server resource name. The name value must be unique among all API servers, and it must be a valid resource name. |
operations |
Map | Optional | Mutable | A map from the operation name to the operation object. Each key must be valid ObjectName, and each value must be a valid operation. Each key must be unique within the operations object, which means the operation key is unique within an API server. No duplicate operation values are allowed; operations with the same paths and methods members are not allowed. The operations object is limited to 25 keys (25 individual operations). |
operations.key |
String | Optional | Mutable | A string that specifies the name of the operation. |
operations.value |
Object | Optional | Mutable | An object that specifies attributes of the operation. |
operations.value.methods |
Array | Optional | Mutable | An array that specifies the methods that define the operation. No duplicates are allowed. Each element must be a valid HTTP token, according to RFC 7230, and cannot exceed 64 characters. An empty array is not valid. To indicate that an operation is defined for every method, the methods array should be set to null. The methods array is limited to 10 entries. |
operations.value.methods.element |
String | Optional | Mutable | A string that specifies the name of the HTTP method. This value is case-sensitive. |
operations.value.paths |
Array | Required | Mutable | An array that specifies the paths that define the operation. This is a required property when an operations object is specified. The same literal pattern is not allowed within the same operation (the pattern of a paths element must be unique as compared to all other patterns in the same paths array). However, the same literal pattern is allowed in different operations (for example, OperationA, /path1 , OperationB, /path1 is valid). The paths array is limited to 10 entries. |
operations.value.paths.element |
Object | Required | Mutable | An object that defines a pattern that identifies the parent operation. |
operations.value.paths.element.pattern |
String | Required | Mutable | A string that specifies the pattern used to identify the path or paths for the operation. The semantics of the pattern are determined by the type. For any type, the pattern can contain characters that are otherwise invalid in a URL path. Invalid characters are handled by performing matching against a percent-decoded HTTP request target path. This allows an administrator to configure patterns without worrying about percent encoding special characters. When the type is PARAMETER , the syntax outlined in the table below is enforced. Additionally, the pattern must contain a wildcard, double wildcard or parameter capture. When the type is EXACT , the pattern can be any byte sequence except for ASCII control characters such as line feeds or carriage returns. The length of the pattern cannot exceed 2048 characters. The path pattern must not contain empty path segments such as /../ , // , and /./ . |
operations.value.paths.element.type |
Enum | Required | Mutable | A string that specifies the type of the pattern. Options are EXACT ( the verbatim pattern is compared against the path from the request using a case-sensitive comparison) and PARAMETER (the pattern is compared against the path from the request using a case-sensitive comparison, using the syntax below to encode wildcards and path segment captures.) |
operations.value.accessControl |
Object | Optional | Mutable | An object that specifies the access control configuration for the operation. |
operations.value.accessControl.group |
Object | Optional | Mutable | An object that specifies the group membership requirements for the operation. The groups array must be non-empty when the group object is included. The groups array must not contain more than 25 elements. |
operations.value.accessControl.group.groups |
Array | Required | Mutable | An array that specifies the list of groups that define the access requirements for the operation. The end user must be a member of one or more of these groups to gain access to the operation. This is a required property if operations.value.accessControl.group is set. The ID must reference a group that exists at the time the data is persisted. There is no referential integrity between a group and this configuration. If a group is subsequently deleted, the access control configuration will continue to reference that group. |
operations.value.accessControl.group.groups.element |
Relationship | Required | Mutable | A Relationship that specifies the ID of the group, wrapped in an object, for future extensibility. This is a required property if operations.value.accessControl.group is set. |
operations.value.accessControl.group.groups.element.id |
UUID | Required | Mutable | A UUID that specifies the group ID. This is a required property if operations.value.accessControl.group is set. |
If a path pattern has a type of PARAMETER
, the following syntax rules apply to the parameter expression:
The pattern must start with a slash.
A single *
(wildcard) matches any character except a /
.
A double **
matches the rest of the path. It cannot be followed by any characters in the pattern.
A path segment can be captured with syntax like /{variable}
.
Nested captures are not allowed, meaning {name1{name2}}
is an invalid expression.
Partial path segment matches are not allowed, meaning /part1{part2}
is an invalid expression.
A literal left curly bracket, right curly bracket, backslash, or wildcard can be matched by preceding the character with a backslash: \{, \{, \\, \*
.
The following characters are not allowed in parameter names:
'{', '}', '\', '/'
.
Parameter names must be unique within an expression, meaning /{name1}/resource/{name1}
is an invalid expression.
ASCII control characters are invalid anywhere in the pattern.
Code | Message |
---|---|
200 | Successful operation. |
201 | Successfully created. |
204 | Successfully removed. No content. |
400 | The request could not be completed. |
401 | You do not have access to this resource. |
403 | You do not have permissions or are not licensed to make this request. |
404 | The requested resource was not found. |