Skip to Content
docsUnderstanding Openapi

Last Updated: 3/11/2026

Understanding OpenAPI Specifications

What is OpenAPI?

OpenAPI Specification (OAS) is a standard, language-agnostic interface description for HTTP APIs. It allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code or additional documentation.

Key Components of the Box OpenAPI Specification

1. Info Object

Contains metadata about the API:

  • Title: Box Platform API
  • Version: Current API version
  • Description: Overview of the API’s purpose
  • Contact: Support and developer resources
  • License: Apache 2.0

2. Servers

Defines the base URLs for the API:

servers:
  - url: https://api.box.com/2.0
    description: Box Platform API

3. Paths

Describes all available endpoints, including:

  • HTTP methods (GET, POST, PUT, DELETE, etc.)
  • Request parameters
  • Request body schemas
  • Response schemas
  • Authentication requirements

4. Components

Reusable definitions for:

  • Schemas: Data models for requests and responses
  • Parameters: Common query, path, and header parameters
  • Responses: Standard response formats
  • Security Schemes: Authentication methods (OAuth 2.0, JWT)

5. Security

Defines authentication mechanisms:

  • OAuth 2.0 flows
  • JWT authentication
  • API key authentication

Box API Structure

Resources

The Box API is organized around resources:

  • Files: Upload, download, and manage files
  • Folders: Organize content in folders
  • Users: Manage user accounts
  • Groups: Create and manage groups
  • Collaborations: Share content and manage permissions
  • Comments: Add comments to files and folders
  • Tasks: Create and assign tasks
  • Metadata: Add custom metadata to content
  • Search: Search for content
  • Events: Monitor user and enterprise events
  • Webhooks: Receive real-time notifications

Common Patterns

Resource IDs

Most resources are identified by a unique ID:

GET /files/{file_id}
GET /folders/{folder_id}
GET /users/{user_id}

Pagination

List endpoints support pagination:

  • limit: Number of items per page (default: 100, max: 1000)
  • offset: Starting position
  • marker: Cursor-based pagination for large datasets

Fields

Control which fields are returned:

GET /files/12345?fields=id,name,size,created_at

Error Responses

Standardized error format:

{
  "type": "error",
  "status": 404,
  "code": "not_found",
  "message": "Not Found",
  "request_id": "abc123"
}

Versioning Strategy

Pre-2025: Unversioned API

Before 2025, the Box API was unversioned. All changes were backward-compatible, and the specification was updated incrementally.

2025 and Beyond: Versioned API

Starting in 2025, Box introduced API versioning:

  • Version Format: YYYY.N (e.g., 2025.0, 2025.1)
  • Breaking Changes: Only in new versions
  • Deprecation Policy: Versions supported for at least 12 months
  • Version Header: Box-Version: 2025.0

Migration Path

  1. Review the changelog for the new version
  2. Test your integration against the new specification
  3. Update your code to handle any breaking changes
  4. Update the version header in your requests
  5. Monitor for deprecation notices

For detailed information, see the Box API Versioning Strategy .

Working with the Specification

Validation

Validate the OpenAPI specification:

# Using Swagger CLI
swagger-cli validate openapi.json
 
# Using OpenAPI Generator
openapi-generator-cli validate -i openapi.json

Linting

Check for style and best practices:

# Using Spectral
npm install -g @stoplight/spectral-cli
spectral lint openapi.json

Conversion

Convert between OpenAPI versions:

# Convert OpenAPI 3.0 to 2.0 (Swagger)
api-spec-converter --from=openapi_3 --to=swagger_2 openapi.json > swagger.json

Tools and Resources

Code Generation

Documentation

Testing

Validation

Best Practices

For API Consumers

  1. Always validate responses against the schema
  2. Handle errors gracefully using the standardized error format
  3. Use the fields parameter to reduce payload size
  4. Implement pagination for list endpoints
  5. Cache responses when appropriate
  6. Monitor API changes by watching this repository

For Contributors

  1. Follow the style guide for consistent formatting
  2. Include examples for all endpoints
  3. Document all parameters with clear descriptions
  4. Add error responses for all failure scenarios
  5. Test changes with validation tools
  6. Update the changelog for breaking changes

Additional Resources

Getting Started