How to Write Documentation for your Machine

Instructions:

• First, describe what your API does and its main purpose.
• Explain the basic principles and concepts behind your machine API.
• Add a glossary table of terms to help users understand key concepts.
• You can use HTTP code snippets like in the examples below to properly show endpoints. Users will be able to test them in the documentation by clicking the "Send request" button (if supported).
• You can also use code snippets (TypeScript, Python, etc.) to show how to interact with the machine programmatically.

Writing good documentation for machine endpoints helps users understand, test, and integrate with your API. Follow these guidelines to make your documentation clear and useful:

General Principles

• Use simple, clear English.
• Document each endpoint separately.
• Always include HTTP request/response examples.
• Describe all parameters, headers, and authentication requirements.
• Add notes about special behaviors, limitations, or security.
• Use placeholders like ${baseUrl} for variable parts of URLs.

Using HTTP Code Snippets

You can use HTTP code snippets (see examples below) to show how to call your endpoints. These snippets allow users to test the endpoint directly from the documentation, for example by clicking a "Send request" button in interactive docs.

Example: GET Endpoint

GET ${baseUrl}/download-image

Example: GET with Headers and Body

GET ${baseUrl}/download-image
test-header: "ABCD"

{
  "property": true
}

Example: POST Form Data

POST ${baseUrl}/externalCallback
x-token: token1234
Content-Type: application/x-www-form-urlencoded

field1=value1&field2=value2

Example: POST Multipart Form Data

POST ${baseUrl}/externalCallback
x-token: token1234
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="file"; filename="test.txt"
Content-Type: text/plain

This is a test file.
--boundary
Content-Disposition: form-data; name="field1"

value1
--boundary
Content-Disposition: form-data; name="field2"

value2
--boundary--

Using Code Snippets

You can also use code snippets (e.g., TypeScript, Python) to show how to interact with the machine programmatically:

console.log('Hello world')

Recommended Structure for Each Endpoint

1. Title: Name of the endpoint.
2. Description: What does the endpoint do?
3. HTTP Request Example: Use HTTP code snippet.
4. Parameters: List and describe all parameters.
5. Headers: List required headers (e.g., authentication).
6. Request Body Example: If applicable.
7. Response Example: Show typical response.
8. Notes: Special behavior, limits, security, etc.

Tips

• Use Markdown headings and code blocks for structure and clarity.
• Prefer HTTP and code snippets for requests, responses, and code examples.
• Always specify required headers and authentication tokens.
• If your endpoint returns files or binary data, describe the format (e.g., base64, binary, etc.).
• Keep documentation up to date with code changes.

---

By following these guidelines and using HTTP/code snippets, your documentation will be easy to read, test, and maintain. Interactive HTTP examples make it simple for users to try endpoints directly from the docs.