APIs and API collections

APIs (application programming interfaces) offer a standard method of communication for software components, and provide a controlled and managed access to data or resources for your API consumers, in other words anything that calls your APIs, be they applications, services, or other APIs.

API usage is on the rise. More and more, web and mobile applications are based on a UI that uses API operations to call to the backend servers for resources and data to provide the functions of the application. APIs are also central for Internet of Things (IoT) and business integration projects. On infrastructure side, microservices architecture takes API proliferation to a whole new level, as individual containers and functions also call APIs to work with the rest of the system.

API definitions

APIs, their functions, operations, accepted incoming and outgoing data, and their security are all defined and described in the API definition (sometimes also called API specification) of the API. The API definition of an API forms the contract towards your API consumers, in a way the "terms and conditions" of your backend data and resources: what they can do and what they must provide to do so.

The OpenAPI Specification

42Crunch Platform supports the OpenAPI Specification (OAS) v2 or later.

Formerly known as Swagger specification, the OAS has emerged as a widely adopted way of documenting REST APIs. It offers a standard format with large tooling support. Instead of trying to deduce the intent of an API from its behavior or source code, the standard OpenAPI contract makes it easier to communicate this clearly.

One of the key functions that the standard contract can enable is API security, because it provides a way for developers, operations, and security people across teams to speak in common language. When all teams building both the API and the infrastructure the API is going to sit in can clearly communicate the intent, requirements, and outcome, it is also easier and more reliable to uncover, understand, and mitigate security risks. This idea is in the core of 42Crunch Platform.

Schema object definitions in the OAS are an extended subset of the JSON Schema Specification Wright Draft 00, and for the most part correspond to how JSON schemas are defined, with some exceptions. Two notable exceptions are that in JSON schema, you can define the property type as an array, often to allow for null properties, and null is a valid type. However, in the OAS, arrays in type or null as a type are not supported.

If you must allow for null properties, in the OAS v3, you can add the property nullable to your schema and set it to true.

The OAS v2 does not have the property nullable. Instead, as a workaround, you can add the OAS extension x‑nullable to your schema and set it to true. Some tooling, such as all features in 42Crunch Platform, support this workaround, but the support is not universal. Using x‑nullable together with required in your schemas can also cause problems. For proper support, we recommend switching from OAS v2 to OAS v3.

API definitions in 42Crunch Platform

You import the OpenAPI definitions of your APIs in JSON or YAML format to the platform. Both OpenAPI Specification v2 and v3 are supported. The file size of your API should not exceed 10 MB.

If you import API definitions in YAML format to the platform, they are automatically converted and stored in JSON format. However, you can continue to view, edit, and download them in YAML format.

When you import an API, API Security Audit runs automatically to check that the API definition is a valid OpenAPI definition, and provides an audit score that reflects how good and secure it is. You can then iterate on improving the security, check that the API implementation matches the API contract, and finally deploy them with protection in place.

An example screenshot showing the API summary page of the Pixi API.

The quickest way to find API definitions in 42Crunch Platform is to click Find API in the main menu. For more details, see View APIs.

Example screenshot of the Find API view, listing the APIs available to the user, the API collections they are in, and the owner of the collection.

If your API definition has regular expressions with either positive or negative lookaheads defined, these may cause weird behavior, for example, in Conformance Scan.

API collections

API definitions in 42Crunch Platform are organized into API collections. API collections group your APIs into meaningful units that are easier to manage than trying to keep track of individual APIs.

You can find all API collections visible to you (either your own collections or collections shared with you) on the API collections page:

An example screenshot of the API collections page

API collections created through CI/CD integration show the source repository and branch from where they originated:

An example screenshot of five API collections where one collection is created through CI/CD integration and shows the repository information.

For quick access, your recent API collections are always shown under the main menu on the left:

An example screenshot showing the list of recently used API collections

When you import an API, you can choose which collection you want to put it into or create a new collection, so you always have a place where to put your APIs. You can create additional collections at any point.

An API can belong to only one API collection at a time. However, if needed, you can import the same API definition into multiple collections and manage each instance of the API separately.

Sharing APIs and access level

All API collections are private by default, meaning that they and the APIs in them are visible only to you. However, you can share API collections with other users in your organization, so they too can access your APIs. Sharing API collections instead of individual APIs makes it easier to keep track of what you have shared and who can see it.

You cannot share API collections if your organization administrator has not given you permission for this function. For more details on user permissions, see Permissions.

Who you can share API collections with, or if you can share at all, is controlled by the permissions your organization administrator has defined for your user account. If you can share API collections, it can be just with named individuals or teams, or also directly with everyone in the whole organization. You can see the sharing status at the top when you view a collection:

An example screenshot that shows the sharing status of an API collection as well as who owns the collection. This collection is shared separately with one user and one team. There is also a button for editing the sharing next to the shring status.

API collections can have four access levels:

An example screenshot showing the four possible access levels a user can have to API collections.

  • Read-only access: Users with read-only access can view the API collection and the APIs in it, as well as the OpenAPI definition, audit and scan reports, and the protection status of the API. Users can also view the transaction logs in Trace Explorer. Users cannot audit, scan, or protect the APIs (including updating existing protection configurations).
  • Read/write access: In addition to above, users with read/write access can import new APIs to the API collection, and change the existing ones. Users can also audit, scan, and protect the APIs, and update existing protection configurations. Users cannot edit the shared API collection itself or share it forward, or delete the collection or APIs in it.
  • Read/write/delete access: In addition to above, users with read/write/delete access can delete APIs in the shared collection. Users cannot edit or delete the shared API collection itself, or share it forward.
  • Full access: These are API collections you have created and own. Full access means that in addition to everything above, you can also change the name or sharing of the API collection, or delete it from the platform.

Organization administrators have access to view and modify all API collections in their organization. This means that all API collections in an organization are visible to all organization administrators like the collections were their own, both on the API Collections page and in the monitoring dashboards. If an organization has several API collections, we recommend using more descriptive collection names that just organization and company name to be able to tell all collections apart.

In addition to choosing who to share a collection with, you can also choose the access you want to give to it. All APIs in an API collection have the same access level, but you can give different access level to different teams or users:

The screenshot shows the sharing of an API collection. The collection has been shared with one team and two individual users, with different access levels. The team has been granted read-only rights, except one team member who can also edit APIs in the collection.

When grouping your APIs into collections, keep sharing in mind. Do not put APIs you do not want to share into a shared collection.

API collections are always owned by a user. You can view who owns a particular API collection in your organization in the API collection list, as well as their email address in case you need to, for example, request access or report an issue with the collection.

An example screenshot showing the name and the email address of the owner of the API collection.

Organization administrators can change the owner of any API collection in their organization to transfer full control of the collection to someone else. If organization administrators need to delete a user account, they must transfer the API collections and APIs of that user to someone else before they can remove the account.

Organization administrators and auditors can also export (in JSON or CSV format) the list of API collections in their organization, including details like:

  • Collection UUID
  • Source (from CI/CD integration or created manually)
  • Sharing and access type (read-only or read/write)
  • Name and platform UUID of the collection owner
  • Email address of the collection owner

This allows, for example, organization administrators to communicate to collection owners when actions are required from them.

The screenshot shows the export icon above the list of API collections and the list of the options for export formats.