Skip to main content
Version: 2019-05-29 (Current)

Schema API

The Schema API provides access to the OpenAPI specification for the Omise API. This allows you to programmatically discover available endpoints, understand request/response structures, and integrate with API documentation tools.

Overviewโ€‹

The Schema API provides:

  • OpenAPI Specification - Complete API documentation in OpenAPI 3.0 format
  • Endpoint Discovery - Programmatically discover all available API endpoints
  • Data Structures - Complete schema definitions for all request and response objects
  • Validation - Use the schema to validate API requests before sending
  • Code Generation - Generate client libraries using OpenAPI code generators

How the Schema API Worksโ€‹

  1. Request the Schema - Make a GET request to retrieve the OpenAPI specification
  2. Parse the Response - The response is a complete OpenAPI 3.0 document in JSON format
  3. Use the Schema - Import into tools like Swagger UI, Postman, or code generators
  4. Stay Updated - The schema reflects the current state of the API

Use Casesโ€‹

API Documentationโ€‹

Generate interactive API documentation using tools like Swagger UI or ReDoc.

Client Generationโ€‹

Use OpenAPI code generators to create type-safe client libraries in your preferred language.

Request Validationโ€‹

Validate API requests against the schema before sending to catch errors early.

IDE Integrationโ€‹

Import the schema into your IDE for autocomplete and type checking.

API Testingโ€‹

Generate test cases based on the schema definitions.

Available Endpointsโ€‹

Schema Formatโ€‹

The schema is provided in OpenAPI 3.0 format and includes:

Pathsโ€‹

All available API endpoints with:

  • HTTP methods (GET, POST, PATCH, DELETE)
  • Request parameters (path, query, body)
  • Response structures for each status code
  • Authentication requirements

Componentsโ€‹

Reusable schema definitions for:

  • Request bodies
  • Response objects
  • Common parameters
  • Security schemes

Securityโ€‹

Authentication requirements:

  • HTTP Basic Auth with API keys
  • Public key vs Secret key requirements

Integration Examplesโ€‹

Swagger UIโ€‹

<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "https://api.omise.co/schema",
    dom_id: '#swagger-ui'
  });
</script>

Postmanโ€‹

  1. Open Postman
  2. Click Import
  3. Enter URL: https://api.omise.co/schema
  4. Import as OpenAPI 3.0

OpenAPI Generatorโ€‹

# Generate a Python client
openapi-generator generate \
  -i https://api.omise.co/schema \
  -g python \
  -o ./omise-python-client

Best Practicesโ€‹

Do Thisโ€‹

  • Cache the schema - The schema doesn't change frequently, cache it locally
  • Version your integrations - Pin to specific schema versions when available
  • Validate early - Use schema validation to catch errors before API calls
  • Generate clients - Use code generators for type safety and productivity
  • Keep tools updated - Ensure your OpenAPI tools support the latest spec

Don't Do Thisโ€‹

  • Don't hardcode structures - Use the schema for dynamic integrations
  • Don't ignore updates - Check for schema updates periodically
  • Don't skip validation - Always validate against the schema in development

Need help? Contact support@omise.co