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 in 42Crunch Platform
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.
You can import API definitions that you choose to the 42Crunch Platform .
- The file size of your API should not exceed 10 MB.
- The OpenAPI Specification (OAS) v2, v3.0, and v3.1 are supported. The API definition must be in JSON or YAML format (
.json,.yaml, or.yml).If you import OpenAPI 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.
- GraphQL schema definition files (
.graphql,.graphqls,.gql,.gqls,.sdl) are supported. GraphQL introspection files are not supported.Support for GraphQL is not enabled by default, but is available as a separate subscription.
When you import an API, API Security Audit runs automatically to check that the API definition is against the standard it claims to follow (the OAS or GraphQL), 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 API Scan.
The OpenAPI Specification
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.
GraphQL specification
GraphQL is an open source standard for query language and execution engine for application services to describe their data model, what kind of interactions can be performed with that data, and what requirements those interactions have in a flexible way.
On the surface, GraphQL looks very much like the OAS. A GraphQL API is a documented interface that clients calling a service can consume to make requests to the service and for the service to respond to those requests. The API document describes data objects as schema definitions as well as operations that can be performed on those data objects. However, there are some fundamental differences the GraphQL specification and the OAS, such as:
- The OAS provides a granular standard way of describing APIs. In GraphQL the type systems described in schema definition files are application-specific. This allows for the flexibility in tailoring the GraphQL API to the exact needs of the application, but the ensuing variation and tailor-made details reduce the footprint of the standard, leaving it on a much more generic level compared to the OAS.
- REST APIs following the OAS can have multiple endpoints. GraphQL APIs have only one endpoint.
- The OAS uses eight standard HTTP protocol methods (
GET,POST,PUT,PATCH,HEAD,TRACE,OPTIONS,DELETE) as API operations. GraphQL has only three types of operations (query,mutation,subscription), all specific to GraphQL. - The OAS supports describing the required authentication methods as part of the documented API contract. GraphQL completely externalizes security measures outside the documented API contract, meaning that they are not described and cannot be deduced from the API definition itself.
- REST APIs following the OAS specify the full contract they offer, including both capabilities and accepted input as well as the outgoing response in full. The APIs of GraphQL services do define the capabilities, but it is the GraphQL clients that specify which of those capabilities they consume and to what extent: the response to a client contains only what it asked for, instead of a predetermined set of data, only part of which the client might use.
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:
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. You can put both OpenAPI and GraphQL API definitions in the same API collection or create separate API collections for each API type, depending which approach suits you best.
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:
- Read-only access: Users with read-only access can view the API collection and the APIs in it, including the raw API contract, 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, including sharing, 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.
