Creating and Editing APIs

This page describes how to easily create, edit and publish your APIs within the Ceptor Console

  • Creating APIs in Ceptor Console

    You can create your APIs by creating an API Group then create a new API within the group and specifying a version of your API

  • Documenting Your APIs

    Document your APIs with OpenAPI specification or use Ceptor's built-in HTML editor

  • Subscriptions and Security

    Choose from a rich set of options for customizing security for your APIs

  • Implementing APIs

    You have several options for how to implement an API and its operations

  • Advanced Implementation Using Pipelines and Tasks

    The Pipelines and Tasks functionality that allows you to drag tasks together to perform different actions

  • Publishing APIs

    Publish your API in an environment and choose whether to restrict the subscription or security settings

Ceptor API Types

Ceptor API Management supports three different types of APIs

OpenAPI Specification

Ceptor supports both version 2 and version 3 of the OpenAPI Specification. Version 3 is highly recommended since it offers more features.

SOAP / WSDL

For SOA / SOAP / WSDL services, you can maintain your WSDL within Ceptor and expose it to your clients.

Plain HTTP

With some services that are less structured or are described in a different format - you can also define these services as plain HTTP services within Ceptor

Creating APIs in Ceptor Console

You can create your APIs by creating an API Group then create a new API within the group and specifying a version of your API

Creating API Groups

An API Group contains your 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

When you create an API Group you can:

  • Specify a name for your API Group
  • Write a description
  • Add any tags that can be used when searching for APIs
Creating API Groups
Creating APIs

Creating APIs

APIs are found in API Groups. API covers one or more versions of that API that are deployed separately. 

When you create an API you can:

  • Decide if any subscription is required
  • Add any additional tags
  • Choose a name for your API
  • Write a description

If subscription is required, your API Partners can subscribe to them choosing one of the defined Subscription Plans, which limits the rate they can call your APIs in.

Creating APIs

Creating API Versions

Once you have created an API, it is time to create a specific version of it.

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 

When you create an API Version you can:

  • Specify a name for this version of your API
  • Specify a base path
  • Select the API Type,
  • Write a description

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 to your new version.

Creating API Version

Documenting Your APIs

Keep track of all your APIs using the OpenAPI specification

Documentation APIs

You should document your APIs as much as possible, so make full use of descriptions for all operations, parameters, attributes etc.

But, in some cases this is not enough and you need a higher level of documentation - or your API might not be OpenAPI Specification, but might be WSDL / SOAP or plain HTTP.

For these cases, you can write documentation for an API using Ceptor's built-in HTML editor. Simply navigate to the Documentation tab for an API version, and begin editing your HTML. You can either use the built-in editor or switch to HTML source mode and write the HTML source code directly.

Documentation APIs

Subscriptions and Security

Get a rich set of options for customizing the security for your APIs

For individual APIs, you can decide if you want to require subscriptions in order to access the API, of if no prior subscription is required.

No matter which option you choose, you can specify individual authentication and authorization requirements on whole APIs or override it per operation.

Subscriptions and Security

Authentication Methods

Below are some of the most common authentication methods, many more are available.

API Key

API Key is the simplest form of authentication, your API Partner applications have one or more API keys defined for them - and any given one of them identifies that API Partner Application as the caller. Note that this API key should be treated as a secret password, which it essentially is.

Client Credentials / Basic Authentication

By enabling basic authentication, you enable your API Partner Applications to authenticate by providing their client_id and client_secret as userid/password in a Basic Authentication. Note that as usual, you should in the Ceptor Gateway ensure that all only https/encrypted connections are used.

OpenID Connect Authentication

Almost the same as OAuth 2.0 authentication, but exposes the OpenID Connection configuration metadata URL in the OpenAPI definition, The URL is usually https://www.yourorganisation.com/.well-known/openid-configuration

Bearer Authentication

This enables authentication using a bearer token, an access token earlier issued using OpenID Connect / OAuth 2.0

OAuth2 Authentication

Essentially the same as bearer authentication, but provides the OAuth 2.0 authorize and token URLs in the OpenID Configuration, and allows specifying what scopes to require.

Other forms of Authentication

You can secure your APIs anyway you want using e.g. SPNEGO / Kerberos, WS-Security, SAML or other means of authentication if you just set it up in the API Gateway.

Authorization Methods

As with any Location in Ceptor Gateway you can specify detailed authorization requirements per API or API operation

Permissions, ACLs and ABAC

Specify a required permission to get access to this location. See authorization for more information.

Permissions and ACLs can contain very advanced functionality, such as ABAC (Attribute-Based Access Control) - see authorization for more information.

Required Roles

List of roles/groups, if any roles are specified, at least one of them is required to access the resources.

Authorization Script

Custom script (JavaScript, Groovy or Python code) which can perform complex authorization decisions

Implementing APIs

You have several options for how to implement an API and its operations.

Mock APIs, or using JavaScript, Groovy or Python

You can use a script to generate a response to your clients - this is ideal for creating mocks or testing stubs for APIs.

If you check one of the override checkboxes for an operation, you will get a script for this particular operation.

Implement APIs using Pipelines and Tasks

If scripts or proxying is not enough for you, you can use Ceptor Gateway's Pipelines and Tasks for your API implementation. 

Proxy requests to backend destination servers

Proxying allows you to proxy the request toward a destination server, and stream its response back to the client.

You can either use a predefined destination for your selected environment, or you can use a custom one you specify yourself.

If you specify a custom destination, you have all the same options available as any destination within the gateway.

Pipelines and Tasks

Drag tasks together to perform differenet actions with the Pipelines and Tasks functionality

When implementing an API in the Ceptor API Gateway, you can take advantage of the Pipelines and Tasks functionality that allows you to drag tasks together to perform different actions. This can be specified per API level and overridden for specific operations.

Examples of tasks are:

  • Calling remote services
    Perform an HTTP request to call a service, or retrieve data from a resource
  • Transform content from XML to JSON and back and combine responses from multiple different requests into one
  • Execute script
    Allows the script to do any processing it wants by running custom code.
  • Call pipeline
    Call another pipeline and run through all its tasks – this allows you to chain pipelines and reuse collections of tasks from other pipelines.
Pipelines and Tasks

Publishing APIs

Before your APIs are available, they need to be published in an environment

To publish an API click Publish for the appropriate environment to publish the API.

It is possible to publish an API, but having it marked as not being available in the Developer Portal - in that case, the API is still accessible (with possible subscription/security restrictions) but not visible within the Developer Portal, so API Partners / Developers cannot try it out from within it.

When you save, the API Gateway is updated and the APIs are immediately available in the given environments that they are published within.

Once your API is published in an environment, you can try it out.

publishing APIs

Contact us

contactus