Creating an API

Every API in Apiway starts with an OpenAPI specification. You can upload one you’ve already written or let Apiway’s design intelligence help you build one from a business context.

Uploading a Specification

Platform API

curl -X POST https://core.api.apiway.net/v1/programmes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments API",
    "specification": "<base64-encoded OAS>"
  }'

Management UI

Navigate to Cartography > APIs and click New API. Upload your .yaml or .json file.

What Happens After Upload

Once your spec is uploaded, Apiway processes it through several services:

1. Specification Parsing

   The OAS is parsed and validated against the OpenAPI 3.x standard. Invalid specs are rejected with specific error details.

2. Compliance Scoring

   The compliance service evaluates your spec against your organisation’s rules — naming conventions, security requirements, documentation completeness, and more. Each violation has a severity (error, warning, info) and remediation advice.

3. Design Recommendations

   The recommendations service analyses your spec for patterns and best practices — missing pagination on collections, inconsistent error schemas, security gaps, header conventions, and versioning alignment.

   Recommendations are suggestions, not blockers. They help you improve API quality over time.

4. Security Analysis

   Apiway inspects the security and securitySchemes sections of your OAS. If your spec defines no security:

   • OAuth 2.0 client credentials is applied automatically
   • Each operation gets a scope based on its operationId
   • Consumers authenticate with client credentials and receive scoped JWTs

   This “secure by default” behaviour ensures no API reaches production without authentication.

API Metadata

Beyond the spec, each API has metadata managed by the platform:

Field	Description
Name	Human-readable name displayed in the catalogue
Technical name	URL-safe identifier (auto-generated from name, lowercase)
Major version	SemVer major version — drives versioning and entitlement boundaries
Description	Summary shown in the developer portal
Business function	Organisational capability this API serves
Exposure	Internal, Partner, or Public — controls visibility in the marketplace

API States

An API moves through these lifecycle states:

State	Meaning
Prospect	Uploaded, not yet deployed — undergoing review
Active	Deployed and serving traffic
Deprecated	Still serving traffic but scheduled for retirement
Retired	No longer available