Public API endpoints for fetching docs

[snazzyDocs]

Publicly available API endpoint(s) to fetch documentations

This will serve as central place to flesh out the requirements, response object shape, etc. for the endpoints.

Key endpoints

• Fetch by group_id
• Fetch by search keyword?

[snazzyDocs]

Requirements

Below are the proposed requirements/spec. If you have any suggestions please feel free to chime in.

Returned response:

{
  "links": {
    "self": "[endpoint-url]"
  },
  "data": [
    {
      "type": "docs",
      "id": "[documentation-unique-id]",
      "attributes": {
        "group_id": "[documentation-group-id]",
        "unique_id": "[documentation-unique-id]",
        "version": "[documentation-version]",
        "language": "[documentation-language]",
        "static": "[JSON string representing documentation]",
        "lookup": "[Flat key/value object of pages]",
        "settings": {
          "logo": "[path-to-logo]",
          "title": "[title]",
          "sub_title": "[sub-title]"
        }
      }
    }
  ]
}

Returned static object:

Currently the documentation content is setup to be returned as a structured object of folders and children.

[
  {
    "id": "JIU-SRCK-46N-QED",
    "name": "Getting Started",
    "path": "/1.0/getting-started",
    "slug": "getting-started",
    "children": [
      {
        "id": "CX0-BLRV-EJT-W8K",
        "name": "Introduction",
        "path": "/1.0/getting-started/introduction",
        "slug": "introduction",
        "type": "page",
        "yaml": {
          "title": "Introduction"
        },
        "content": "<h1>Introduction</h1>\n<p>The page content</p>",
        "children": []
      },
      {
        "id": "9QX-31C6-6GQ-02T",
        "name": "Quick setup",
        "path": "/1.0/getting-started/quick-setup",
        "slug": "quick-setup",
        "type": "page",
        "yaml": {
          "title": "Quick setup"
        },
        "content": "<h1>Quick setup</h1>\n<p>The page content</p>",
        "children": []
      }
    ]
  }
]

Returned lookup object:

The lookup object is a flat key/value object of all pages in the documentation. Endpoint will have an optional lookup_key parameter to define which key to use for the pages(eg. id, path, slug, etc.). By default the lookup object is returned keyed by page id.

{
  "JXO-TPZ-EKP-ARK": {
    "id": "JXO-TPZ-EKP-ARK",
    "name": "Introduction",
    "path": "/getting-started/introduction",
    "slug": "introduction",
    "type": "page",
    "parent": "/getting-started",
    "content": "<h1>Introduction</h1>\n<p>Page content</p>",
    "children": [],
    "isVisible": true,
    "parent_id": "E1C-DLY-GS1-WUV",
    "last_updated": "Oct 20, 2022"
  },
  "PNQ-S5W-DPL-FZR": {
    "id": "PNQ-S5W-DPL-FZR",
    "name": "Quick start",
    "path": "/getting-started/quick-start",
    "slug": "quick-start",
    "type": "page",
    "parent": "/getting-started",
    "content": "<h1>Quick start</h1>\n<p>Page content</p>",
    "children": [],
    "isVisible": true,
    "parent_id": "E1C-DLY-GS1-WUV",
    "last_updated": "Aug 8, 2022"
  }
}

[snazzyDocs]

Parameters

Below are the proposed parameters. If you have any suggestions please feel free to chime in.

version, language, uid(unique_id of doc), lookup_key

[snazzyDocs]

By group ID

This endpoint is being developed and nearly done. It will use the parameters/filters as above.

By search term endpoint

This endpoint is being developed. It will use a ?search=term url parameter to search the content in pages in documentations of a defined group_id (including the same parameters/filters as above)

[snazzyDocs]

Done. https://docs.snazzydocs.com/1.0/api/documentations