Endpoints: documentation tab

[kasp1]

The DOCS tab in the Endpoint interface should allow documenting the selected endpoint.

The UI holds a version of the server's setup, which is a JSON of endpoints and collections (in the Vuex store). Documenting an endpoint means adding several specific properties to the selected endpoint's object in this JSON.

This is an example of a documented endpoint:

    "POST /posts": {
      "comment": "Creates a new news post.",
      "params": {
        "text": {
          "required": true,
          "regex": "^.{10,}$",
          "comment": "The post text."
        },
        "status": {
          "required": false
        },
        "payment": {
          "required": false
        },
        "area": {
          "required": true,
          "regex": "^\\d+$",
          "comment": "Area in which this post belongs to."
        },
        "advertisement": {
          "required": true,
          "regex": "^\\d$",
          "comment": "Is this post advertisement (value: 1) or regular news posts (value: 0)? "
        },
        "media": {
          "required": false,
          "regex": ".*",
          "comment": "Comma-separated list of file IDs."
        }
      },
      "restrict": true,
      "ownership": true,
      "response": {
        "text": {
          "present": "always",
          "type": "string",
          "comment": "The updated post text."
        },
        "area": {
          "present": "always",
          "type": "bool (1|0)",
          "comment": "The updated area in which this post belongs to."
        },
        "advertisement": {
          "present": "always",
          "type": "bool (1|0)",
          "comment": "Updated value of whether this post is an advertisement or regular news post."
        },
        "status": {
          "present": "always",
          "type": "string",
          "comment": "Current status of the post."
        },
        "payment": {
          "present": "always",
          "type": "number",
          "comment": "Payment ID that was recorded for this post (only in case of advertismenets) or 0."
        },
        "media": {
          "present": "always",
          "type": "string",
          "comment": "Comma-separated list of file IDs."
        }
      }
    }

The documentation specific properties are:

• The comment property of the endpoint itself, describes the general purpose of the endpoint.
• The comment property of each request parameter (in the params object), describes what value should be supplied to the parameter.
• The response object is overall just designed to document the endpoint's response unless it's an error. This object contains for each JSON property in the response body:
  • type - a string saying what type is the value, may be selected from a drop down menu as String or Number
  • present - a string saying in what conditions is the property present, may be e.g. always or if anotherPropert == true we've got no convention for this yet, suggestions welcome.
  • comment - a comment saying what is the value of the parameter.

All the mentioned documentation properties are optional. The UI should provide a way of editing these in the DOCS tab of each endpoint. There's no UX, suggestions are welcome.

[kasp1]

Thank you very much for the PR, it looks great.

It seems like in the documentation tab there are switches for "Ownership" and "Restrict" options:

I suppose these are corresponding with the ownership and restrict properties of an endpoint. These properties are part of the actual setup of the endpoint and are not meant just for documentation and so they are being setup on the "configuration" page:

If I understand things right here, we can omit these two switches in the documentation tab.

Another thing I noticed is that the endpoint parameters are currectly created just in the "configuration" tab, but the response parameters are supposed to be created in the documentation tab as they are purely just informative. Is there any way to add or remove a response parameter besides editing them?

Thanks for clarification.

[ltbringer]

The ownership and restrict options can be omitted.

Currently, only those response parameters are shown, which are present in the endpoint object. To add response parameters, there can be a form (like the ones for the new params on configurations tab) which can be populated for each response parameter.

That makes me think? why not support response addition/deletion at the configurations tab?

[kasp1]

Perhaps because the response has literally nothing to do with the server's functionality unlike the request parameters. It's purely just informative for third parties who would like to use the API (it can be also seen at the GET /apiko/reference endpoint).

[ltbringer]

In that case, we can have:

1. Response section removed.
2. Response section as read only.

Adding/Deleting response on the documentation tab doesn't seem quite right unless I am missing some points? Suggest if there could be other ways to handle?

[kasp1]

If the response section was just read-only, there would be no way editing it. The GET /apiko/reference endpoint is just a generated document (that can be sent to anyone who is not supposed to have access to the Dev UI), it has no editing capabilities.

Since the response object is there purely to document an endpoint's response, it makes sense to me to put it under documentation tab.

Might be useful to ask others for opinions as well.