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

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.

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.

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:

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

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

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:

API collections can have four access levels:

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:

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.

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.