Ceptor Docs

Page tree
Skip to end of metadata
Go to start of metadata

In the API Management Configuration, you setup environments, rate limits and subscription plans as well as destinations and target servers if needed.


JSON

For details about the JSON attributes in the configuration, please see Data Structures.

Within the API Management menu, select "Configuration", this will bring up API Management Configuration looking similar to this:


Here, you can set up your environments, add rate limits and subscription plans.

Environments

Environments can be used to separate where an API is deployed - within the API Gateway, you configure in which case an environment is hit - it can be as simple as a particular hostname, or you can add all sorts of other conditions, like specific Client IP Addresses, request content-types, user/group or any other information that can be derived from the request.

When clicking add to add a new environment to your configuration, you get this box:

Type in the name of the environment, and the URL for where it will be implemented, e.g. https://api-test.example.com

Save it, and then you can edit the details.

Here, you should enter a description of the environment, and the URLs for Oauth2 authorization, token refresh and discovery.

These URLs are used within the OpenAPI specification, when enabling OAuth2 or OpenID Connect security for your API. Note that OpenID Connect support is not available for OpenAPI 2, since it requires OpenAPI 3 to be supported in the specification.
It is still possible to select it, and it will take effect within the API Gateway, but you cannot express the fact inside the OpenAPI 2 specification.

This is an example of how it could look when using https://api-test.example.com as the base URL.

You can also add destinations - see Config - Destinations for full details. A destination is a set of (possible clustered) application servers which your request can be forwarded to - the ones in these settings can be reused for this particular environment in the implementation of the API, if you are either proxying to the API, or using the Pipelines and Tasks to call APIs as part of your implementation.

Note that you do not need to add any destinations here in order to be able to call them - it is still possible to define them for each individual API - but the advantage of doing it here, is that the configuration is reused and any changes - e.g. adding more servers - take effect for all APIs configured to use this predefined destination.

Refer to Setting up API Gateway for details on how to use implement that specific environment within one (or a cluster of) API Gateways.

Rate Limit Groups

Rate limit groups are used within subscription plans to impose limits on the number of requests within a given time period. This allows you to impose limits on clients depending on the chosen subscription plan, such as limiting the number of API calls to 1000 an hour, but at most 50 a second.

You can add any number of groups you wish - e.g. click on Add, and type in Internal-Only as the name.

After saving, you can select it and edit the details.


Click Add to Add a new Rate limit.

Enter the maximum number of calls per time period - for time period, you can choose between second, minute, hour, day, week, month and year.

You can add multiple limits per group, such as 100 per second, 1000 per hour and 10000 per day.

Subscription Plans

A subscription plan contain a rate limit group, and can be tied to a particular API

Here, you can create a new plan, select a Rate Limit Group for it and enter its name and description.

You can also choose if this plan should be part of new APIs by default - if it is, when you create a new API and enable subscription for this API, this plan will be one of the selectable by default, as in the example below:

A subscription plan can also require approval from an administrator.

A subscription plan that does not require approval allows an API Partner to select and use it immediately.

You might want to allow such free plans with limited number of requests so your API Partners can try out requests before committing to a higher limit plan.




API Profiles

API Profiles allow you to specify common settings that span across multiple different APIs - in addition, you can put limitations on what a developer can specify for an individual API.

An API Profile allows you to:

  • Specify shared security settings
  • Specify shared request modification settings
  • Limit changing security
  • Limit implementation options
  • Limit which destinations can be selected for proxying
  • Limit publishing
  • Control subscription options
  • and more...

Changing these options can significantly simplify the API Designer user interface, limiting which options your API Designers can access and view.

When creating an API profile, you can specify security settings and request modification settings and restrict publishing of APIs to specific environments.
This allows you to reuse settings across different APIs using the same API profile, and it allows you to change settings for all those APIs at once.

If an API profile e.g. does not allow an API Designer to specify security settings for the API, the tab where he normally sets security up is simply not shown. If the profile however allows changing the security settings, the API Designer gets the option to use the default or override the settings for his API.
The same is true for request modification which can be useful for e.g. rewriting URLs, adding or removing API keys or authentication information before proxying APIs.


Below, is a list of the API Profile configuration, here, you can add additional profiles, and you can optionally require that all new APIs that are created also need an API Profile specified.



When editing an individual API Profile, you get the options below:

The following options can be set

Name

The name of the API Profile.

Description

A short description of the API Profile

Required Roles

List of 0 or more required roles - if any roles are listed here, an API Designer needs at least one of these roles/groups to be able to assign the API profile to an API.

This allows you to choose which API Designers gets access to which roles.

You might want to require an API Profile to be selected for new APIs - if you do, and also create a set of API Profiles, you can require your API Designers to choose an API Profile for their APIs. You can then use these profiles to restrict what they can do - e.g. you can specify request modification and security settings for the APIs, in which case these tabs simply will not show up on the API Designers screens.

This gives you a much simpler API for some API Designers if required.

You can use API Profile Permissions to control who can bypass the restrictions setup in an API Profile, allowing e.g. administrators to override security settings on specific APIs even if API Designers are prevented from doing this due to the restrictions on an API Profile.


API Subscription settings

Here, you control the default subscription settings for APIs using this Profile, and you control if they can be changed on the individual API.

Allow overriding subscription required setting

Check this to configures subscription per API instead of on the API Profile.

Specify Request Modification Defaults

If set, allows you to configure Request Modification settings on the API Profile - see Request Modification for more information.
If checked, a new page shows up underneath the API Profile where you can edit the settings:

Allow overriding Request Modification

If checked, your API Designers are allowed to override the request modification on their API when they have selected this API Profile.

Specify Security Defaults

If set, allows you to configure Security settings on the API Profile - see Securing APIs for information on how to set this up.

Allow overriding Security Defaults

Check this to allow an API Designer to change the security settings on an API. If not checked, he will not see the Tab displaying the security settings, and what is specified in the API Profile will be used instead.

Allow specifying Security Options per operation

If not checked, an API Designer is not able to specify specific security settings per operation - they instead are configured for the entire API.

Like with any other settings on the API Profile, you can allow individual users full control so they can bypass the limitations set on the API Profile - see permissions for info.

Limit Implementation Methods

If checked, you can limit which implementation options (Proxy, Script, Pipeline & Tasks) the API designer can choose between.

Allow specifying Implementation per operation

If not set, the API Designer is not able to change implementation options per operation in an API.

Allow publishing

Here, you can control if your API designer is allowed to publish an API or not.

Allow editing API Version JSON Spec

If not set, it is not possible to edit the API Version JSON specification directly from the API Designer. Note that this is not the OpenAPI Spec, but the entire APIVersion structure as described in: Data Structures

Environments

Here, you can limit which environments are available for use within an API using this API Profile - e.g. you can restrict publishing to only a Sandbox environment for an API Designer, and you an allow an administrator to bypass this limitation and publish other environments.

Limit Destinations

If an API is implemented using proxying, you can specify a subset of allowed destinations to be used.

API Profile Permissions

Permissions to use an API profile are controlled by group membership, configured directly on the API Profile - this controls who is allowed to select a particular API profile for an API.

If any groups are defined, membership of at least one of these groups are required in order to use the profile.

ACLs

ACLs (Access Control Lists) however can override what is specified in the API Profile, the following ACLs are defined, and allow bypassing the restrictions that might have been setup in an API Profile.

If these ACLs are not defined, it means that the user using the Ceptor Console does not have access.

Note: This is contrary to many other uses of ACLs, where commonly if an ACL is not defined, then the resource is considered unprotected.


In the following, XXXX is a name of a specific API profile.

ACL namePermissionDescription

api.profiles.edit
api.profile.XXXX.edit

executeAllow editing of all or a specific API Profile
api.profiles.override.all
api.profile.XXXX.override.all
executeAllows overriding all limitations specified within an API Profile
api.profiles.override.publish
api.profile.XXXX.override.publish
executeAllow overriding any limitations specified in an API profile regarding publishing.
api.profiles.override.editjsonspec
api.profile.XXXX.override.editjsonspec
executeAllows overriding limitations specified in an API profile regarding editing the API Version specification directly.
api.profiles.override.security
api.profile.XXXX.override.security
executeAllows overriding security settings in APIs within a profile.
api.profiles.override.implementation
api.profile.XXXX.override.implementation
executeAllows overriding implementations of APIs within a profile
api.profiles.override.subscription
api.profile.XXXX.override.subscription
executeAllows overriding any request modification settings specified an an API profile.
api.profiles.override.requestmodification
api.profile.XXXX.override.requestmodification
executeAllows overriding any request modification settings specified an an API profile.
api.profiles.override.environment
api.profile.XXXX.override.environment
executeAllows overriding any limitations on environments that might be set in an API Profile.
  • No labels