OpenAPI Specification

SheetsToJson automatically generates an OpenAPI 3.0 specification for each registered Google Sheet, making it easy to integrate with API tools and generate client libraries.

Accessing Your OpenAPI Spec

Each sheet has its own OpenAPI specification available at:

https://api.sheetstojson.com/docs/{sheetId}/openapi.json

Replace {sheetId} with your Google Sheet ID.

Interactive Documentation

View and test your API interactively using Swagger UI:

https://api.sheetstojson.com/docs/{sheetId}

The Swagger UI provides:

• Interactive testing - Try API calls directly from your browser
• Request/response examples - See exactly what data to send and expect
• Schema validation - Automatic validation based on your sheet structure
• Authentication testing - Test with your API keys

What's Included

The OpenAPI specification includes:

Endpoints

All available operations for your sheet:

• GET /api/v1/{sheetId}/{tabName} - List rows
• GET /api/v1/{sheetId}/{tabName}/{rowId} - Get single row
• POST /api/v1/{sheetId}/{tabName} - Create row(s)
• PUT /api/v1/{sheetId}/{tabName}/{rowId} - Update row
• DELETE /api/v1/{sheetId}/{tabName}/{rowId} - Delete row

Data Models

Automatically generated schemas based on your sheet columns:

{
  "User": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "name": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "created_at": { "type": "string", "format": "date" }
    }
  }
}

Security Schemes

API key authentication configuration:

{
  "securitySchemes": {
    "ApiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key"
    }
  }
}

Using the Spec

Generate Client Libraries

Use the OpenAPI Generator to create client libraries in your preferred language:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate JavaScript client
openapi-generator-cli generate \
  -i https://api.sheetstojson.com/docs/abc123/openapi.json \
  -g javascript \
  -o ./client

# Generate Python client
openapi-generator-cli generate \
  -i https://api.sheetstojson.com/docs/abc123/openapi.json \
  -g python \
  -o ./client

Supported languages:

• JavaScript/TypeScript
• Python
• Java
• Go
• PHP
• Ruby
• C#
• Swift
• And 50+ more!

Import into API Tools

Import your OpenAPI spec into popular API development tools:

Postman

1. Open Postman
2. Click Import
3. Enter your OpenAPI URL: https://api.sheetstojson.com/docs/{sheetId}/openapi.json
4. Click Import

Your entire API will be available as a Postman collection with pre-configured requests.

Insomnia

1. Open Insomnia
2. Click Create → Import From
3. Select URL
4. Enter: https://api.sheetstojson.com/docs/{sheetId}/openapi.json
5. Click Fetch and Import

VS Code REST Client

Create a .http file:

@baseUrl = https://api.sheetstojson.com
@apiKey = your_api_key_here

### Get all users
GET {{baseUrl}}/api/v1/abc123/Users
X-API-Key: {{apiKey}}

### Create user
POST {{baseUrl}}/api/v1/abc123/Users
X-API-Key: {{apiKey}}
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]"
}

Schema Updates

The OpenAPI spec is automatically updated when:

• You refresh your sheet schema
• Column names or types change in your Google Sheet
• New tabs are added or removed

To force an update:

curl -X POST \
  -H "X-API-Key: your_api_key" \
  https://api.sheetstojson.com/api/abc123/refresh-schema

Example OpenAPI Spec

Here's a simplified example of what the generated spec looks like:

{
  "openapi": "3.0.0",
  "info": {
    "title": "My Database API",
    "version": "1.0.0",
    "description": "Auto-generated API for Google Sheet"
  },
  "servers": [
    {
      "url": "https://api.sheetstojson.com"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/{sheetId}/Users": {
      "get": {
        "summary": "List all users",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/User" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "email": { "type": "string" }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}

Best Practices

1. Version Control: Download and commit your OpenAPI spec to track API changes over time
2. Client Generation: Use the same spec version across all client libraries for consistency
3. Validation: Use the spec to validate requests/responses in your tests
4. Documentation: Share the Swagger UI link with frontend developers
5. Mock Servers: Use tools like Prism to create mock servers from your spec

Next Steps

• Learn about rate limits
• View code examples