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.
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 away 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
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
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.
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.
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 repository and the 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.
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 account belongs to the free community organization, or your organization administrator has disabled this function for you. For more details on 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 three access levels:
- 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 the existing protection configuration.
- Read/write access: In addition to above, users with read/write access can import new APIs to the API collection, and change or delete the existing ones. Users can also audit, scan, and protect the APIs, and update the existing protection configurations. 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:
When grouping your APIs into collections, keep sharing in mind. Do not put APIs you do not want to share into a shared collection.
You can also view who owns a particular API collection in your organization (excluding the free Community 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.