| Info |
|---|
See also Glossary |
Environments
Within Ceptor API Management, you can set up multiple different environments - what they are and how they are used is entirely up to you and your organisation.
Some organisations want to have a Sandbox and a Production environment, where the Sandbox environment is used in production, but with fake data to test implementations. Others have multiple different test environments, where an API needs to go through the various environments. You can add as many environments as you need.
For each environment, you configure a number of URLs used to fill in the security definition in the Swagger / OpenAPI API definitions.
A specific version of an API is published in one or more environments, where it is then available for use by API partners.
To serve APIs, Ceptor Gateway is configured to serve APIs on a specific location, e.g. one that is reached if the hostname is api.example.com or sandbox.example.com
Within the Gateway Configuration, you specify what environment to serve APIs from in the given configuration, and you decide how rate limits are implemented and where to store API Usage information.
Destinations
Within an environment, you can set up a number of destinations that can be used as a target for proxies in the implementation of an API - a Destination for an API is exactly like a Destination in the Gateway - see Config - Destinations for more information.
These destinations can then be used as predefined destinations within the implementation of a service, or the service can use a custom destination and set of servers just for itself.
Configuring and using predefined destinations makes it easier to change them by adding target servers to a cluster or changing settings for them - all APIs using this predefined destination will then use the new settings.
Below is an example of an API implementation which proxies requests to a custom destination:
and here is an example using a predefined destination:
API Groups
An API Group is a container, it can also be thought of as a category for APIs - it can contain any number of APIs which in turn contains API versions.
This allows you to separate APIs into multiple groups.
APIs
Within an API group, you define an API - any number of APIs can be contained in an API Group
You can also restrict who gets read and write access to administering your APIs so you can control who can view or edit them within the Ceptor Console.
For an API, you specify if a subscription is needed, and if it is, you must specify which subscription plans that your API partners can choose from - see API Management Configuration for information on how to define your own subscription plans.
Within an API, you have one or more API Versions - multiple versions can be published at one time and within different environments, so it is possible (and makes good sense) to test out new versions on one environment before publishing it in another.
API Versions
An API version is a specific version of an API - it contains information about the API itself, its structure, input/output data and its implementation.
A good API version contains thorough documentation and examples on all operations and parameters as well as response content. It is up to you how to describe and document your API.
Ceptor supports 3 different types of APIs;
- openapi
An API version described using OpenAPI / Swagger description format - for more information, see the full specification at https://github.com/OAI/OpenAPI-Specification - Ceptor supports both version 2 and version 3 of the OpenAPI specification - Version 3 is highly recommended since it offers more features. - wsdl
For SOA / SOAP / WSDL services, you can maintain your WSDL within Ceptor and expose it to your clients. - plainhttp
Some services are not that structured or are described in a different format - you can also define these services as plainhttp services within Ceptor - to Ceptor, such a service is published at a particular base URL, and made available there - there is no specification describing the input/output data like when using openapi or wsdl but you can still implement the service directly within Ceptor, or proxy requests to destination servers.
API Definition
For openapi type APIs, you define the API content within Ceptor using the OpenAPI / Swagger standard - Ceptor supports both version 2 and 3 of this standard.
In the specification, you can add operations and parameters either using the GUI like below:
or you can edit the specification directly using Ceptor's builtin OpenAPI definition editor:
It is entirely up to your preferences what way to define your API - some API designers prefer to edit the specification directly.
| Info | ||
|---|---|---|
| ||
You can also use a remote OpenAPI specification which is loaded at runtime, and periodically refreshed - this is often useful if you use other tools like e.g. Spring Boot to generate the OpenAPI specification from code - in this case, you do not need to copy all changes to Ceptor and keep the two versions in sync - just pointer Ceptor at the URL for the specification, and the gateway will ensure that it is refreshed periodically and made available to clients. |
Security
No matter what type of API you have, you can get Ceptor to secure access to your API, and you can require subscriptions (and this limit usage by subscription plan).
When authenticating or authorizing API calls, you have the full power of Ceptor gateway available - see full details of all authentication methods supported directly in the gateway here: Location - Authentication
On the API Version level, you can specify a subset of the authentication methods, but within the Ceptor Gateway where the specific API environment is published, you can add additional authentication methods.
For individual operations on openapi type APIs, you can override the security settings for each individual operation.
Note that you can use scripts (Javascript, Python or Groovy) to do custom authorization checking - see Scripts and Macros for more information on executing scripts within the gateway.
If no authorization restriction is applied, and no subscription is required, APIs are accessible anonymously without clients / API partners needing to identify themselves.
| Warning |
|---|
When using remote OpenAPI Specifications, you cannot specify security settings individually per operation, since operations might change frequently, so to guard against security threats by new locations not being protected properly, security settings can only be defined on the API Version level and not on the individual operation level when using remote OpenAPI specifications. |
Implementation
Within Ceptor, you can implement your APIs in different ways;
| Info |
|---|
You can define implementations either for all environments, or specifically for a given environment - this allows you to e.g. proxy requests in one environment, and return mock responses in another. |
You can choose between these methods:
- Execute script
This allows you to run Javascript, Groovy or Python scripts to create and send a response to your API - this is often used for mocking API calls in a sandbox environment, but the full power of the script system is available, so you can implement your APIs fully. - Proxy to Destination
When using Ceptor purely as an API Gateway, you will often just proxy requests onward to clustered application servers - this allows you to use either preconfigured destinations for a specific environment or specify your own API version specific destination and target servers. - Pipelines and tasks
This allows you to implement an API using Pipelines and Tasks, where you can drag tasks into a pipeline and execute them - see Pipelines and Tasks for additional information.
| Warning |
|---|
If using scripts extensively which can blocks threads while executing long-running tasks, ensure that you configure the Config - Gateway Settings accordingly so you have enough working threads available to leave resources available for other clients. |
| Info |
|---|
When creating an implementation for APIs using OpenAPI specification, Ceptor will analyze the specification, and create a sample response for you corresponding to the schema with pre-filled data and comments helping you creating a response that exactly matches the specification.
Also, note that any defined parameters are available to the script as variables pre-filled with the input values sent from the client. |
Request modification
This is particularly useful when proxying requests to other destinations - it allows you to modify request/response headers and cookies as well as rewrite URLs.
All of Ceptor Gateway's Scripts and Macros are available for use here.
Publishing
Once an API version is published in a given environment, it is available for use - possibly restricted by the subscription or security settings.
Note that it is possible to publish an API, but having it marked as not being available in the Ceptor API Developer Portal - in that case, the API is still accessible (again with possible subscription/security restrictions) but not visible within the Developer Portal, so API Partners / Developers cannot try it out from within it.
API Partners
An API Partner has information about a partner or consumer of APIs - A partner can be thought of as a specific group or organisation that has applications which use your published APIs.
API Partners can self-register within the Developer Portal, or they can be created and managed from Ceptor Console.
API Partners contains name, contact information, and can have assigned roles and users/developers each with different permissions.
API Partner Applications
A given application partner can have any number of Partner Applications registered - a partner application can be subscribed to a number of APIs, and within it, redirect URLs, client IDs and secret as well as API keys are maintained. Partners themselves have access to some of these attributes within the Developer Portal, but not all. From within the Ceptor Console, however you have full access to all attributes and can restrict partners to use e.g. only certain OAuth2 grant types/flows and scopes.
Developers
API Developers are individual developers associated with an API Partner - one developer can be associated with multiple different partners, and can have different roles at each partner. Developers log on to the Developer Portal, and can use it to browse, subscribe to and try out the different available APIs.
Developer Portal
Ceptor Developer Portal is used by Developers working for API Partners to self-register and access your APIs as well as subscribe to them, choosing between the different subscription plans you have made available per API.
The Developer Portal provides self-service functionality to developers, where a developer can sign up and create and maintain his API Partner Organisation and register his applications.
It also enables developers to discover new APIs, subscribe to them, view their documentation and try them out.
Also, any security credentials are also maintained by the developers here.