Chapter 1. 3scale Terminology

Access tokens are keys used to authenticate when calling the Account Management API, the Analytics API and the Billing API.

ActiveDocs is the 3scale specification for documenting REST APIs. ActiveDocs is based on the popular Swagger framework. With ActiveDocs, APIs get interactive documentation which makes it easier for developers to understand web services and also to test them without any installation.

From the Admin Portal, API providers can configure the integration of their API with 3scale, manage their application plans, give access to internal members and external customer, limit traffic per application keys, customize their developer portal… This is the central console for API providers to manage and secure the access to their API. The Admin Portal contains the Dashboard as the starting point.

An API is a logical bundle of one or more methods which are accessible. A given API provider may expose one or more such APIs. The term API is used interchangeably with the word Service.

3scale also has it’s own APIs which are located in the 3scale ActiveDocs, available in your Admin Portal, under the Documentation 3scale API Docs section.

APIcast is an NGINX based API gateway used to integrate your internal and external API services with 3scale API Management Platform. An API Gateway is the interface that handles API requests. Depending on its configuration it can handle access control, rate limiting, security filtering, logging, routing, caching…​

For more information about APIcast and its deployment options (hosted, self-managed and different configuration options), check out the APIcast Overview.

Credentials are a set of keys, secrets or identifiers associated with an Application which permit the application to access an API. The form the credentials take depends upon the authentication pattern in use for the API.

An individual, group or company that accesses an API provided by an API provider. The term may refer both to the organization and the software applications written by the organizations to use the API. A given organization may have one or more applications which access the API.

An API Key is a type of credential for an application to be allowed to make calls on a specific API. API Keys are a specific type of authentication pattern.

In our documentation and guides, the “API provider” (3scale customer) is the individual, group, or company that owns one or more APIs and manages them using the 3scale API Management Platform. An API provider may make their APIs accessible to other teams internally within their organization or externally to third-party developers, partners, or the public.

An application is piece of software code which is developed by an API Consumer to access an API. The application will normally have associated to it within the 3scale system a unique set of api credentials for the API, a traffic history of the calls sent to the API and meta-data captured at Application creation. Applications are linked to developer accounts.

Authentication is the process of verifying the identity of a user or server requesting access. This process precedes the authorization process which determines the resources that can be accessed.

A technical scheme used for a given API to express the credentials needed by an API Consumer to access a methods on an API. Each API within 3scale can have one and only one authentication pattern selected.

This is the host URL e.g. https://my-api.com

Plugins provide a wrapper for the 3scale API that enables API Access Control and API Traffic Reporting without having to run another server. A plugin lives inside the code that powers your API. The plugin calls the 3scale API for Access Control & Traffic Reporting.

Same as “Integration options”. In 3scale, we usually refer to ‘deployment options’ when talking about ways of deploying the APIcast gateway (not the 3scale API Management Platform).

Developer accounts are the accounts subscribed to a particular API. Developer Accounts are the parents of the applications. When new developers subscribe to an API, an application is automatically created for them which will allow them to make calls to the API it is subscribed to.

The developer portal is the site where developers can subscribe to APIs. From the developer portal, developers can manage their subscription, have access to their API key, create applications, access the interactive API documentation (ActiveDocs), see their API consumption, etc. The 3scale CMS, with its out of the box features allows to quickly create a developer portal with all what is required for on-boarding new customers.

An endpoint is a specific call or transaction which can be made on an API by an application. A method usually corresponds to one specific action that can be taken such as getting a list of objects or creating a new object. An API normally has multiple endpoints. The term is equivalent to the "method" term.

End users are the users of an application which calls one or multiple API(s).

From the Field Definition section in the Admin Portal it is possible to add and/or create new fields for gathering data from internal admins/members, from developer accounts and from applications. These are the fields which are displayed when a new account is created. For example, to the developer signup form on the developer portal, additional fields can be added, such as for example ‘address’. These fields can be made optional or required.

Integration errors are generated by 3scale when calls are performed with an incorrect set of credentials or token, or for calls with incorrect Ids, URLs… These errors might be errors coming from the application which is calling the API or can be a configuration error with the integration of the API with 3scale.

Integration options, also known as deployment options, are the available options for integrating an API with the 3scale Management Platform (NGINX, plugins…).

The mapping rules map incoming calls from specific endpoints to the corresponding methods and metrics created in 3scale.

Usage tracking, endpoint access and limits are based on the methods and metric[metrics] that are configured with these mapping rules.

See our documentation on Mapping Rules.

Methods let you track the usage of your API on 3scale. You can add a method for each of the HTTP methods available on the API endpoints for your API. Methods are hit-based. By default on 3scale, method calls trigger the built-in Hits-metric. To track other types of events you can add Metrics that report in different units. Usage limits and pricing rules for individual methods are defined from within each Application plan.

See our documentation Defining Your API (Methods And Metrics).

Metrics let you track specific calls to your API by mapping them to one or more URL patterns in the Mapping Rules section of the integration page. Metrics are cumulative and not discrete. The built-in top level metric on 3scale is Hits. Other top level metrics can be added if needed.

See our documentation Defining Your API (Methods And Metrics).

The term “Monetization” or “API monetization” refers to the fact of charging customers based on API access and/or on usage. API Monetization can be done through plans.

Plans are used for granting access to specific APIs and endpoints, limiting traffic and monetizing API usage. 3scale has four different types of plans that can be used on their own or in conjunction:

Potential upgrades are developer accounts that triggered traffic limit alerts. These developer accounts could potentially be upgraded to a plan meeting their needs in terms of traffic volume.

A pricing rule is a logical expression set to determine the cost of a particular transaction in the system. To charge for use of your API, you will create pricing rules within plans to determine billing and levels of access. You can learn more in how to Provision Paid Plans.

A rate limit is associated with a plan and is a logical expression which definies a threshold on usage by API Consumers of a particular method, endpoint or metric.

These limits are configured in the Application Plans, you can read more here.

In 3scale, both the term 'API' and 'Service' are used to refer to API services. An API service is a logical bundle of one or more methods (or endpoints) which are accessible. A given API provider may expose one or more such API services.

3scale also has it’s own APIs in the 3scale ActiveDocs, available in your Admin Portal, under the Documentation 3scale API Docs section.

Service tokens are keys used to authenticate when calling the 3scale Service Management API.

A contract (plan) between an account and a service.

See ActiveDocs.

Webhooks are processes which are triggered following an event, webhooks work as an instant notification mechanism.

See our documentation on Webhooks.