Json To Api

---
name: json-to-api
description: design rest api endpoints from json data with openapi 3.0 spec
license: MIT
metadata:
  version: "1.0"
  category: data
  author: wangjipeng
  sources:
    - https://github.com/MiniMax-AI/skills
---

# json-to-api

## intent

use this skill when a user provides json data and asks you to design a rest api contract around it. triggers include "create an api for this", "design an endpoint", "write the openapi spec", "make this a web api", or "what would the request/response schema look like". the skill produces endpoint definitions, http methods, status codes, and full openapi 3.0 schemas derived from the json structure, not implementation code or a running server.

## inputs

- **json payload** (required): pasted json, file path, or raw object. can be single object, array, nested structure, or flat key-value config.
- **user intent** (required): explicit request to design an api, create endpoints, or write a spec. without this, skill does not activate.
- **resource name preference** (optional): user-stated name for the primary resource (e.g., "call this 'users'"). if absent, infer from json keys.
- **mode flag** (optional): `/json-to-api` for base spec, or `/json-to-api/expand` for production features (pagination, filtering, sorting, sub-resources).

## procedure

**step 1: parse and classify the json structure**

input: raw json payload.
1. receive the json (validate it parses without syntax error).
2. classify the root data type:
   - single object: likely a resource entity (e.g., `{id: 1, name: "alice"}`).
   - array of objects: likely a collection (e.g., `[{id: 1, ...}, {id: 2, ...}]`).
   - nested object: indicates sub-resources or embedded relationships (e.g., `{user: {id: 1, address: {street: "..."}}}`).
   - flat key-value: configuration or state object (e.g., `{apikey: "...", timeout: 30}`).
3. identify candidate resources by examining top-level keys and nesting depth. mark each key as either a primary resource, sub-resource, or property.
4. infer field types: string, number, boolean, null, array, object. note which fields are always present vs. sometimes absent or null.

output: resource map (e.g., users, addresses, tags) and field inventory with types and optionality.

**step 2: design http endpoints and methods**

input: resource map from step 1.
1. for each primary resource, assign standard http verbs based on json shape:
   - single object: `get /{resource}/{id}` (retrieve), `put /{resource}/{id}` (full replace), `patch /{resource}/{id}` (partial update), `delete /{resource}/{id}` (remove).
   - array of objects: `get /{resource}` (list all), `post /{resource}` (create new).
   - sub-resources (nested objects): `get /{resource}/{id}/{subresource}`, `patch /{resource}/{id}/{subresource}`.
2. use plural nouns for collection endpoints (`/users`, not `/user`).
3. do not invent endpoints not implied by the json structure.
4. assign standard http status codes: 200 (success), 201 (created), 204 (no content), 400 (bad request), 404 (not found), 500 (server error).

output: endpoint table (method, path, summary, expected body, expected response shape).

**step 3: build openapi 3.0 specification**

input: endpoint table and field inventory from steps 1 and 2.
1. initialize openapi 3.0 skeleton with title, version, and servers (if provided).
2. for each endpoint, add a path object with operationId, summary, parameters (query, path), requestBody (for post/put/patch), and responses.
3. for each resource, create a schema component:
   - map json field names to openapi types (string, integer, number, boolean, array, object).
   - mark required fields (fields always present in the json).
   - mark optional fields with `nullable: true` or omit from required array.
   - include `example` values copied directly from the provided json.
   - use `format: date-time` for timestamp strings (if evident from value or user context).
4. for array responses, wrap items in a `data` envelope: `{data: [{...}, {...}]}` or `{data: [...], count: 2}`.
5. validate that every field in the original json appears in the schema.

output: complete openapi 3.0 yaml file, valid and renderable in swagger ui.

**step 4: validate and document**

input: openapi spec from step 3.
1. checklist:
   - every json field is in the schema with correct type.
   - http methods follow rest conventions (no get with request body, no put without body, etc.).
   - status codes are standard, not arbitrary.
   - endpoint paths and names are consistent in casing (plural collections, singular ids).
   - schema property names are consistent (camelCase vs. snake_case matches json).
   - examples in schema match provided json values exactly.
2. flag any deviations and correct them.
3. add brief description to each endpoint explaining its purpose.

output: validated openapi spec ready for delivery.

## decision points

**if user provides json AND explicit api design intent:**
activate skill and proceed through steps 1-4.

**else if user provides json but no api intent:**
clarify: "do you want me to design api endpoints for this json, or something else (transform, validate, document)?"
do not proceed with skill.

**if json is a single flat object (no nesting, no arrays):**
design a single resource with get/{resource}/{id}, put, patch, delete. do not invent collection endpoints.

**else if json is an array of objects:**
design list (get /{resource}) and create (post /{resource}) endpoints. include individual resource endpoints (get /{resource}/{id}, put, delete).

**if json has nested objects:**
decide: treat nested objects as sub-resources (separate endpoints) or as embedded properties (include in parent schema). default to sub-resources if nesting is 2+ levels deep or if user mentions "relationship" or "association".

**if user requests `/json-to-api/expand` mode:**
add pagination (limit, offset, or cursor), filtering (query params per field), sorting (sort param), and explicit sub-resource endpoints. include query param schemas in the spec.

**if json has nullable or optional fields:**
mark them as not required in schema. set `nullable: true` if field appears in json as null.

**if json has timestamp or date fields (iso8601 strings or unix integers):**
use `format: date-time` or `format: date` in schema, not generic string type.

**if user has not stated a primary resource name:**
infer from json top-level keys or context. if ambiguous, ask user: "should the primary resource be called 'users' or 'accounts'?"

**if json contains authentication tokens, passwords, or secrets:**
flag them as sensitive in the schema documentation. recommend not including in example; suggest `format: password` for schema clarity.

**if json payload is malformed or does not parse:**
stop and report syntax error with line number. do not guess or auto-correct.

## output contract

deliverable: one valid openapi 3.0 specification in yaml format.

structure:
- openapi 3.0.0 header with info object (title, version, description).
- servers array (empty if no base url provided; user can add later).
- paths object with one entry per endpoint (get, post, put, patch, delete).
- components.schemas object with all resource schema definitions.
- each schema includes type, required array, properties (with types, examples, descriptions), and additionalProperties: false (strict).

file location: return as yaml code block in response, labeled "openapi-spec.yaml". if user requests file, save to local path or provide download link.

example structure (abbreviated):
```yaml
openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      operationId: listUsers
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
    post:
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: Created
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Alice"
      additionalProperties: false
    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        count:
          type: integer
          example: 2

validation: spec must be parseable as yaml, must pass openapi 3.0.0 schema validation, and must render without errors in swagger ui or redoc.

outcome signal

user knows the skill worked when:

1. openapi spec renders cleanly in swagger ui or redoc with no validation errors.
2. every json field appears in the schema with the correct type and at least one example value from the input json.
3. endpoint paths are sensible: plural collection endpoints (/users), parameterized resource endpoints (/users/{id}), nested sub-resources if applicable.
4. http methods match the json shape: get for reads, post for creates, put/patch for updates, delete for deletes. no get with request body, no put without body.
5. status codes are standard: 200 for get/put/patch success, 201 for post success, 204 for delete success, 400 for validation error, 404 for not found, 500 for server error.
6. request/response bodies are defined: requestBody for post/put/patch, responses with proper content-type and schema ref.
7. field naming is consistent: all property names match the json exactly (camelCase matches camelCase, snake_case matches snake_case).
8. optional/required fields are marked correctly: required array includes only fields always present in the input json; optional fields are either omitted from required or marked nullable.
9. user can copy the spec into an api gateway or code generator (e.g., openapi-generator, prism, swagger-codegen) and get working scaffolding without manual edits.

if any of these signals is absent, the skill output is incomplete or incorrect. ask user for clarification or re-run step 4 (validate).

original author: wangjipeng (github.com/MiniMax-AI/skills)

credits: this enriched version adds explicit decision logic, edge case handling (malformed json, authentication fields, timestamp inference), expanded validation rules, and detailed outcome signals per implexa standards. ```