Parameter Documentation — Complete Guide

DodaTech Updated 2026-06-28 7 min read

In this tutorial, you will learn about Parameter Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Parameter documentation describes each input your API endpoint accepts including the parameter name, location, data type, format, required status, default value, constraints like minimum and maximum, and a realistic example showing the expected format.

What You'll Learn

How to document parameters by location, what metadata every parameter needs, how to describe constraints and validation rules, how to show parameter examples, how to document complex nested parameters, and how to handle parameter deprecation.

Why It Matters

Parameters are where most integration bugs originate. Developers send the wrong type, forget required fields, or use incorrect formats. Clear parameter documentation with types, constraints, and examples prevents these errors before they happen.

Real-World Use

The DodaTech API's parameter documentation includes type (string, integer, boolean), format (uri, uuid, date-time), required status, default value, constraints (minimum, maximum, pattern, enum), and a realistic example for every parameter. This comprehensive documentation reduced parameter-related support tickets by 60 percent.

Parameter Types and Locations

flowchart TD
  A[API Parameters] --> B[Path Parameters]
  A --> C[Query Parameters]
  A --> D[Header Parameters]
  A --> E[Body Parameters]
  B --> F[Resource identifiers]
  C --> G[Filtering, pagination, sorting]
  D --> H[Authentication, idempotency, tracing]
  E --> I[Complex data payloads]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Path Parameters

Path parameters are part of the URL path. They identify resources.

#### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Unique file identifier. Format: `file_` followed by 16 lowercase alphanumeric characters. Example: `file_a1b2c3d4e5f6g7h8` |
| `jobId` | string | Yes | Unique job identifier. UUID v4 format. Example: `c7f3a2b1-8d4e-4f5a-9b6c-1d2e3f4a5b6c` |

**URL template:** `/v2/files/{fileId}/compress`
**URL example:** `/v2/files/file_a1b2c3d4e5f6g7h8/compress`

Query Parameters

Query parameters appear after the ? in the URL. They handle filtering, pagination, sorting, and options.

#### Query Parameters

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| `page` | integer | No | 1 | minimum: 1 | Page number for pagination |
| `per_page` | integer | No | 20 | minimum: 1, maximum: 100 | Items per page |
| `sort` | string | No | `created_at` | enum: `created_at`, `name`, `size` | Sort field |
| `order` | string | No | `desc` | enum: `asc`, `desc` | Sort direction |
| `status` | string | No | `all` | enum: `active`, `archived`, `deleted` | Filter by status |
| `q` | string | No | — | maxLength: 200 | Search query for filtering by name |

Header Parameters

Header parameters go in the HTTP headers. They handle authentication, tracing, and content negotiation.

#### Header Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `Authorization` | string | Yes | Bearer token. Format: `Bearer YOUR_API_KEY` |
| `Content-Type` | string | Yes | `application/json` for JSON APIs, `multipart/form-data` for file uploads |
| `Accept` | string | No | Response format: `application/json` (default) |
| `Idempotency-Key` | string (uuid) | No | UUID to prevent duplicate processing. Store the key with the request and resend on failure |
| `X-Request-ID` | string (uuid) | No | UUID for request tracing. Include when contacting support |

Body Parameters

Body parameters are complex nested objects in the request payload.

#### Body Parameters

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `file_url` | string (uri) | Conditional | — | Public URL of the file. Required if `file` is not provided. Example: `https://example.com/report.pdf` |
| `file` | binary | Conditional | — | Direct file upload. Required if `file_url` is not provided |
| `format` | string | No | `zip` | Compression format: `zip`, `gzip`, `sevenz` |
| `level` | integer | No | 6 | Compression level 1-9. Higher levels reduce size but increase processing time |
| `password` | string | No | — | AES-256 encryption password. Must be 8-64 characters. If provided, the output archive is encrypted |
| `metadata` | object | No | — | Custom metadata key-value pairs. Maximum 20 keys |

**Nested parameter:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `metadata.key` | string | No | Metadata key. Max 100 characters |
| `metadata.value` | string | No | Metadata value. Max 500 characters |

Documenting Constraints

Be specific about every constraint on the parameter.

#### Parameter Constraints

| Constraint | Example | Description |
|------------|---------|-------------|
| enum | `zip`, `gzip`, `sevenz` | Must be one of the listed values |
| minimum | 1 | Minimum value for numeric parameters |
| maximum | 100 | Maximum value for numeric parameters |
| minLength | 8 | Minimum string length for passwords |
| maxLength | 64 | Maximum string length for passwords |
| pattern | `^file_[a-z0-9]{16}$` | Must match the regular expression |
| format | `uri`, `uuid`, `date-time`, `email` | Must match the standard format |

Parameter Deprecation

Document deprecated parameters with sunset dates and replacements.

#### Deprecated Parameters

| Parameter | Deprecated In | Sunset Date | Replacement |
|-----------|---------------|-------------|-------------|
| `compression` | v2.0.0 | 2026-09-01 | Use `format` instead |
| `callback_url` | v2.0.0 | TBD | Use webhooks instead |

Deprecated parameters continue to work until the sunset date but trigger
a warning header: `Warning: 299 - "Parameter 'compression' is deprecated"`

Common Mistakes

1. Missing Type Information

Parameters without type documentation cause type errors in strongly-typed languages. Always document the data type.

2. No Default Values

Parameters without documented defaults force developers to guess what happens when they omit the field.

3. Unclear Required Status

Marking required fields without conditional logic causes confusion. Some parameters are conditionally required based on other fields.

4. No Example Values

Parameters without examples force developers to guess the format. Realistic examples are essential.

5. Missing Constraints

Not documenting minimum, maximum, pattern, or enum values causes validation errors that could be prevented.

6. Mixing Parameter Locations

Documenting path parameters alongside query parameters in one table causes developers to misplace them in the request.

7. No Deprecation Timeline

Removing parameters without warning breaks integrations. Document deprecation with clear sunset dates and replacements.

Practice Questions

1. What are the four parameter locations and when do you use each?

Path for resource identifiers, query for filtering and pagination, header for authentication and metadata, body for complex data payloads.

2. What metadata should every parameter include?

Name, location, type, required status, default value, constraints, description, and a realistic example.

3. How do you document conditionally required parameters?

State the condition clearly: Required if file_url is not provided. Mark both conditionally required fields as optional in the table and explain the condition in the description.

4. Why include default values in parameter documentation?

Default values tell developers what happens when they omit a parameter. This is essential for optional parameters with non-obvious defaults.

5. Challenge: Document all parameters for an API endpoint that includes path, query, header, and body parameters. Include at least 10 parameters with types, constraints, defaults, and examples.

FAQ

What is the difference between a parameter and a property?

Parameters are inputs to an API operation. They can be path, query, header, or body values. Properties are fields within a JSON object, typically in the request body or response body.

How do I document enum parameters?

List all valid values in the description or as a code block. Show the default value if any. Example: Values: zip (default), gzip, sevenz.

Should I document deprecated parameters?

Yes. Mark them as deprecated, show the deprecation version, sunset date, and replacement parameter. Continue to accept deprecated parameters until the sunset date.

How do I document parameters with complex nested schemas?

Use a table with dot notation for nested fields (metadata.key, metadata.value) or link to the full schema definition in the components section.

What format should parameter examples use?

Use the same format the parameter accepts. For query parameters, show the URL-encoded value. For body parameters, show the JSON value. For headers, show the exact header value.

Mini Project: Write Parameter Documentation

Choose an API endpoint with at least 8 parameters across multiple locations. Write complete parameter documentation including type, location, required status, default, constraints, description, and example for each parameter. Include deprecated parameters with sunset dates.

What's Next

Parameters are inputs. Now learn to document outputs with Response Documentation. Then explore Multi-Language Code Examples for showing requests in different programming languages.

← Previous Endpoint Documentation — Complete Guide Next → Response Documentation — Complete Guide

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation