This section describes how to create and your APIs from within the Ceptor Console.
See these subsections for more details:
- API Types
- Editing OpenAPI Definition
- Editing WSDL Definition
- Securing APIs
- Request Modification
- Implementing APIs
- Publishing APIs
- Documenting APIs
- Try out API
From within the Ceptor Console, select "APIs" from the API Management menu.
Refer to API Management Configuration for information on how to set up different environments settings that are used from the APIs you create.
An API Group contains APIs - you can create as many API Groups as you need. From the APIs menu, you can see the currently defined groups, and create new API groups.
Note that in the top right corner, you can see how many APIs and versions are created within each API Group.
From the toolbar, you can switch between viewing only API Groups, or a table view with all APIs and versions listed in the hierarchy.
By pressing Search, you can toggle the search pane:
when present, you can search for your API by entering specific text to search for, selecting specific API types, base path patterns and environments.
When Search is activated, empty API groups are not shown - only the ones with content matching the search parameters are shown in the list.
You can click "Create API Group" to create a new API.
It asks you to fill in the name and a description of the group.
Click an API Group to view the APIs within it.
When you click an API group, you can see all the APIs currently with it, and you can edit its detail.
Here, you can add any tags that can be used by your or your API Partners when searching for APIs.
You can also restrict read or write access to specific groups of administrators using Ceptor Console - (see Access Control for information on defining groups and users)
Note the breadcrumb view at the top, where you can always click to get back up the hierarchy.
APIs are found in API Groups - an API covers one or more versions of that API that are deployed separately.
You decide if subscription is required in order to access the APIs - if so, your API Partners can subscribe to them choosing one of the defined Subscription Plans which limits how the rate they can call your APIs in.
Click "Create API" to create a new API.
This brings up this prompt, where you fill in the name and description:
Clicking on the API brings you to this screen:
Here, you can edit the details, add any additional tags, and select if subscription is required in order to call your API. If subscription is required, you should select the applicable Subscription Plans for this API - see API Management Configuration for details on how to create your own subscription plans.
Once you have created an API, it is time to create a specific version of it, click "Create Version" to do just that.
An API Version is a specific version of an API - e.g. "Version 1", "v1", "v1.1" or any other name you wish to assign to it
Note that API Partners subscribe to your APIs - meaning they get access to any published version - if you want separate versions to require different subscriptions, you should place them within separate APIs.
Creating a new API brings up this screen:
Here, you must specify a name for this version of your API, a base path and you can choose to create a new API Version from a template, or copy an existing one. If you choose to copy, all settings, implementations and API specification information will be copied over to your new version.
Select the API Type here (see API Types) and fill in the template and description.
If you want Ceptor API gateway to automatically create the CORS headers (see https://en.wikipedia.org/wiki/Cross-origin_resource_sharing for details) depending on the parameters you specify and their location, you should enable this.
You can also specify that the API is private and not visible in the developer portal - you will usually want that until you have tested it yourself and are satisfied with the implementation.
The "Private" setting only affects the visibility in the Developer Portal - if the API is published to an environment, it is still available no matter what this is set to - but setting it to Private means that it will not show up in any searches done in the Ceptor API Developer Portal.
Ceptor comes with some ready-made templates that help you get started creating your APIs.
Currently, the following templates exist:
- OpenAPI 2 Hello World
This is a simple hello-world API with one operation that returns a hello message. It is written to use OpenAPI specification version 2.
- OpenAPI 3 Hello World
This is a simple hello-world API with one operation that returns a hello message. It is written to use OpenAPI specification version 3.
The Swagger Petstore application is a more complete example of an API with many different operations.
An empty API, with no operations defined.
Copying from another API
You can choose to copy from an existing API, this will copy everything except for the name and base path.
When copying, you can select one of the existing APIs to copy from.
Creating from API Version JSON
Instead of copying from an API, you can also choose to paste in the complete API Version JSON structure, as previously exported from an API implementation.
The created API
After creating the API, click it to see the details.
You can click "API Version details..." to show and edit the details for the API:
Here, you can also add additional tags, and edit the basic information on the API, such as the name, description and base path - as well as the CORS and private flags.
You can optionally load the API from a remote location - this is useful if you create the OpenAPI Specification programmatically using some kind of application framework, e.g. Spring Boot - in that case you do not need to bother with copying the OpenAPI definition into Ceptor - you can instead tell Ceptor to load it from remote.
Some restrictions apply to the Security and Implementation of APIs within Ceptor when loaded from remote; since Ceptor cannot rely on the specific operations being present, you are restricted to specifying implementation and Security options on API level, and cannot override them per operation.
When loading from remote, you can choose to load it directly from an URL (in which case, Ceptor Console and API Gateway will load from the URL you specify directly) or you can choose to load from a configured proxied destination. In the latter case, Ceptor API Gateway will load the OpenAPI description from one of the available target servers in your destination - see Implementing APIs for more details.
Converting from OpenAPI v2 to OpenAPI v3
If your API is in OpenAPI v2 / Swagger format, you can convert it to OpenAPI v3 if you wish to do so, just click the "Convert" toolbar button that appears if your OpenAPI format matches version 2.
Editing API JSON directly
If you prefer, you can also edit the API Version JSON directly - the format is documented in Data Structures
This can be very useful if you want to use the Admin API for updating API Versions, since it allows you to generate the API implementation elsewhere and either upload the changes using the Admin API, or via the API Designer user interface here directly.
It can also be used as a method of copying an API from one environment to another if you have completely separate Ceptor installations.
You can edit the specification either directly by clicking the Edit button, or in the UI, by editing the operation or its parameters.
Here, you can also create new operations and remove existing ones.
If you press the Edit button in the toolbar, you get this screen:
Here, you can edit the OpenAPI definition directly on the left - any changes you make will immediately be visible on the right - and any eventual errors will be shown so you can correct them before saving.
Click "Update" to update, saving any changes.
If you look closer at the API Version screen, you can see it contains 5 tabs:
- API Definition
See Editing OpenAPI Definition for more details about editing the API definition.
See Securing APIs for details about how to specify authentication and authorization settings for your API version.
- Request modification
Before processing the API request, e.g. proxying it, you can modify the request - see Request Modification for more information.
See Implementing APIs for details.
Refer to Publishing APIs for details.
See Documenting APIs for details.