Note: this component stores cluster-wide configuration data and is mirrored across all servers in the topology within the the same cluster.
Note: changes to cluster-wide configuration objects are immediately and automatically mirrored across all servers within the same cluster, so offline changes are not supported.
An API Endpoint represents an endpoint at an API service that is protected by the Data Governance Server Gateway, which acts as a facade and policy enforcement point (PEP) for the API service.
An API Endpoint defines the mapping between a request path received by the Data Governance Server Gateway Servlet and the request path for a request forwarded to an API service. An API Endpoint also defines various settings that control how requests and responses to and from an API service are handled by policies.
↓Relations from This Component
↓Relations to This Component
↓Properties
↓dsconfig Usage
The following components have a direct aggregation relation from API Endpoints:
The following components have a direct aggregation relation to API Endpoints:
The properties supported by this managed object are as follows:
| General Configuration Basic Properties: | Advanced Properties: |
|---|---|
| ↓ description | None |
| ↓ inbound-base-path | |
| ↓ outbound-base-path | |
| ↓ api-server | |
| Authorization and Policies Basic Properties: | Advanced Properties: |
| ↓ service | None |
| ↓ policy-request-attribute | |
| ↓ http-auth-evaluation-behavior | |
| ↓ access-token-validator |
| Property Group | General Configuration |
| Description | A description for this API Endpoint |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Property Group | General Configuration |
| Description | The base path to use for incoming HTTP requests handled by this API Endpoint. The inbound-base-path value may be parameterized by enclosing parameter names in curly braces, as in "/users/{userId}/friends", which would match requests URI paths beginning with "/users/XYZ/friends" or "/users/1234/friends", for example. Parameter values are used in two ways:
|
| Default Value | None |
| Allowed Values | The value must start with a forward slash and must represent a valid HTTP URI path. The value may be parameterized by enclosing parameters in curly braces. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Property Group | General Configuration |
| Description | The base path used in requests forwarded to the downstream API server. The value may be parameterized by enclosing parameters in curly braces, as in "/users/{userId}/friends". When constructing the URI path for requests forwarded to the downstream API server, the parameter values used will be those obtained by applying the client request path to the inbound-base-path value. Any parameters named in the outbound-base-path value must therefore also appear in the inbound-base-path value. |
| Default Value | None |
| Allowed Values | The value must start with a forward slash and must represent a valid HTTP URI path. The value may be parameterized by enclosing parameters in curly braces. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Property Group | General Configuration |
| Description | Specifies the HTTP server that hosts the API that will be proxied by this API Endpoint. |
| Default Value | None |
| Allowed Values | The DN of any API External Server. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Property Group | Authorization and Policies |
| Description | An identifier for the API service that will be used as an input for policy requests. The service name is used by policies to target requests for a particular API. |
| Default Value | If a service name is not specified, then the name of this API Endpoint will be used. |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Property Group | Authorization and Policies |
| Description | A custom key/value pair that will be added as an attribute to all requests made to the policy enforcement point by this API Endpoint. |
| Default Value | None |
| Allowed Values | A key/value pair using the form KEY=VALUE. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Property Group | Authorization and Policies |
| Description | Determines how this API Endpoint will handle HTTP authenticated requests for the purpose of policy enforcement. Currently, only bearer token authentication is supported. |
| Default Value | evaluate-and-forward |
| Allowed Values | do-not-evaluate - The API Endpoint will not attempt to evaluate or modify the HTTP authentication scheme. If an "Authorization" request header is provided, it will be forwarded to the API server as-is. If this value is chosen, policies that impact this API Endpoint should not enforce constraints regarding request authentication, such as access token validity. evaluate-and-forward - If a supported HTTP authentication scheme is used, the API Endpoint will attempt to evaluate the authentication credentials and make authentication information available for policy processing. If an "Authorization" request header is provided, it will be forwarded to the API server as-is unless a policy result specifically prevents the API Endpoint from doing so. evaluate-and-discard - If a supported HTTP authentication scheme is used, the API Endpoint will attempt to evaluate the authentication credentials and make authentication information available for policy processing. If an "Authorization" request header is provided, it will be removed from the request that is forwarded to the API server, effectively stripping HTTP authentication from the forwarded request. evaluate-and-replace - If a supported HTTP authentication scheme is used, the API Endpoint will attempt to evaluate the authentication credentials and make authentication information available for policy processing. Any existing "Authorization" header will be removed from the request that is forwarded to the API server and replaced with an "Authorization" header containing the basic auth credentials configured for the external server designated by this API Endpoint's api-server property. If this value is chosen, the API server will receive a fixed set of credentials, and policies will be responsible for ensuring that the original requester is authorized appropriately. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Property Group | Authorization and Policies |
| Description | If specified, the Access Token Validator(s) that may be used to validate access tokens for requests submitted to this API Endpoint. This property is ignored if the http-auth-evaluation property has a value of "do-not-evaluate" or if the request does not use the RFC 6750 bearer token authentication scheme. |
| Default Value | If no validators are specified, then any of the Access Token Validators configured for this server may be used to validate an access token. |
| Allowed Values | The DN of any Access Token Validator. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured API Endpoints:
dsconfig list-api-endpoints
[--property {propertyName}] ...
To view the configuration for an existing API Endpoint:
dsconfig get-api-endpoint-prop
--endpoint-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing API Endpoint:
dsconfig set-api-endpoint-prop
--endpoint-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new API Endpoint:
dsconfig create-api-endpoint
--endpoint-name {name}
--set inbound-base-path:{propertyValue}
--set outbound-base-path:{propertyValue}
--set api-server:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing API Endpoint:
dsconfig delete-api-endpoint
--endpoint-name {name}