Skip to main content

Project architecture

Your Serverless project is divided in few directories.

Docs​

The first folder docs contains all of your developer portal documentation.

It is composed of 3 main files: index.md, sidebar.json and theme.css

The first one, index.md contains your developer portal homepage information.

You can customise it as you want using markdown syntax.

The second file sidebar.json contains the instructions to build your left sidebar for your portal.

Finally, the last file theme.css contains the CSS for your developer portal.

Entities​

The entities folder contains your routes.

Cloud APIM Serverless organizes API management using two key entities: Routes and Backends.

  • Routes: These define the paths or endpoints of your API. Routes specify how incoming API requests are mapped to backend services. Each route includes details such as the HTTP method (GET, POST, PUT, DELETE), URL path, request parameters, and any middleware or policies applied (e.g., authentication, rate-limiting).

  • Backends: These are the actual services or servers that handle the API requests. Backends can be any HTTP service, such as RESTful APIs, microservices, or serverless functions. Each backend configuration includes the service's URL, authentication details, and load balancing settings.

Together, Routes and Backends allow Cloud APIM Serverless to efficiently manage and direct API traffic, ensuring that requests are securely and reliably processed by the appropriate services.

Modules​

In this folder you can find and create your own Javascript modules.

JavaScript modules are reusable pieces of code that can be exported from one file and imported into another. They help organize and encapsulate code, making it more maintainable and easier to manage. Modules enable better structuring of applications by allowing developers to split functionality into distinct files, each responsible for a specific task. This promotes code reuse, reduces conflicts, and improves overall code quality.

Developer portal​

dev-portal.json is your configuration file for your API portal. You can edit it to rename your documentation portal title, add services such as monetisation and much more !

The Cloud APIM Serverless Developer Portal is a user-friendly platform designed to streamline the interaction between developers and your APIs. Key features include:

  • Automated Documentation: Comprehensive, automatically generated API documentation.
  • Interactive API Explorer: Test and experiment with API endpoints in real-time.
  • Code Samples and SDKs: Ready-to-use code samples and SDKs in multiple languages.
  • Usage Guides: In-depth guides and tutorials for common and advanced API use cases.
  • Authentication Management: Tools for generating and managing API keys and tokens.
  • Real-Time Analytics: Insights into API usage, performance, and error tracking.
  • Community and Support: Integrated forums, Q&A, and support systems for developer collaboration and assistance.

The Developer Portal enhances the developer experience by providing all the necessary resources to understand, integrate, and utilize your APIs efficiently.

For more information, check this tutorial

OpenAPI​

And finally, openapi.json is the file which contains all of your api routes.

Add your own OpenAPI routes, edit them with a code editor or manually with our graphical interface.

OpenAPI is a standardized format for defining and documenting APIs, providing a clear and consistent structure for API descriptions. Key features include:

  • Standardized Specification: Defines API endpoints, request/response formats, parameters, and authentication methods.
  • Machine-Readable Format: Uses JSON or YAML for easy parsing and automated processing.
  • Comprehensive Documentation: Provides detailed and consistent API documentation.
  • Tooling Ecosystem: Supports a wide range of tools for generating client libraries, server stubs, and interactive documentation.
  • Interactive Documentation: Enables the creation of interactive portals like Swagger UI for exploring and testing APIs.
  • Lifecycle Management: Facilitates versioning and change management for APIs.

OpenAPI enhances API development and integration by promoting clarity, consistency, and automation, benefiting both API providers and consumers.

Read this article about OpenAPI routes to create your first one !