elasticio/api-docs

Docs for elastic.io API

api-docs's Issues

Api.elastic.io should have a favicon

Currently, it is hard to identify the tab with api.elastic.io/docs in the browser because there is no favicon.

The ghosts of users are displayed in "Get organization" response

STR:

1. Send the next cURL

curl -X GET \
  https://api-sparrow.elastic.io/v2/organizations/59d22e7eeb865b0018adc247/ \
  -H 'accept: application/json' \
  -H 'authorization: Basic aGFubmEudHJvdHNlbmtvQGVsYXN0aWMuaW86OTc0MGE3OWMtOWRmNy00MDAyLTk3MjItMjc4YjkzNTU1OWIy' \
  -H 'cache-control: no-cache' \
  -H 'postman-token: 654844ce-fb04-1158-fae8-95a1663b5d7e'

AR:

ER: Only existed users are displayed

Investigation for "Poll a result of an execution"

The delay between Retrieve component’s select model and Poll a result of an execution (talking about the same exec_ID) was about 40 minutes.

AR:

• Response from Poll a result of an execution was:

{
    "data": {
        "id": "5aafc115d0516d0007758238",
        "type": "execution-result",
        "links": {
            "self": "/v2/exec/result/5aafc115d0516d0007758238"
        },
        "attributes": {
            "result": {
                "data": {
                    "available": "Available",
                    "pending": "Pending",
                    "sold": "Sold"
                }
            }
        }
    },
    "meta": {}
}

• No Location headers.
  Status code: 200.

ER:

• Status code: 303.
• There is Location header.

API docs describe the not-existing feature

api docs

It's not clear from the docs how to set up schedule of a task.

The Organization admin has access to all tenant's users with "Retrieve all users" request

Preconditions

API docs say:

AUTHORIZATION
This request is authorized to only a user with TenantAdmin role (contact support to get this role).

STR:

1. Create request with Organization API key

AR:

{
    "data": [
        {
            "id": "560e5a27734d480a00000002",
            "type": "user",
            "links": {
                "self": "/v2/users/560e5a27734d480a00000002"
            },
            "attributes": {
                "first_name": "Igor",
                "last_name": "Drobiazko",
                "email": "[email protected]",
                "company": "elastic.io GmbH",
                "registered": "2015-10-02T10:19:19.697Z",
                "last_login": "2018-02-08T16:07:52.495Z"
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 1,
        "total": 646,
        "total_pages": 646
    }
}

ER: an error about authorization

Using Tenant API key in request return the same response as above

Get rid of elasticio mentions

There are still some elasticio mentions that we need to get rid of in order docs to be better white labeled.

The unneeded "URL PARAMETERS" at Poll a result of an execution

POST /v2/workspaces is located under Contracts

Which is wrong

Provide doc more human-acceptable for page[number] parameter

Can't get response "Result ready" from "Poll a result of an execution"

STR:

1. Send the next cURL

curl -X POST \
  https://api-sparrow.elastic.io/v2/components/5a0eca5d2715bf0018058ba3/versions/latest/select-model \
  -H 'authorization: Basic aGFubmEudHJvdHNlbmtvQGVsYXN0aWMuaW86ZGY4MTVlZTMtYjRiZi00MTE2LWFmN2MtMjczNWQ4YjA0YjY1' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: 8e39cfdb-68b8-c668-62f9-d8c82d3ab4c4' \
  -d '{
    "data": {
        "type": "select-model",
        "attributes": {
            "module": "getPetsByStatusWithDynamicSelectModel",
            "method": "getStatusModel",
            "fields": {
                "id" : "1",
                "name" : "value",
                "status" : "sold",
                "category" : {
                	"id":"1",
                	"name":"dogs"
                }
            }
        },
        "relationships": {
            "credential": {
                "data": {
                    "id": "5a6f3e121030f30007bdfa57",
                    "type": "credential"
                }
            }
        }
    }
 }'

2. Copy the "id" from response
3. Send the next cURL with small delay during about 2 minutes:

curl -X GET \
  https://api-sparrow.elastic.io/v2/exec/poll/{PREVIOUS_EXEC_ID} \
  -H 'authorization: Basic aGFubmEudHJvdHNlbmtvQGVsYXN0aWMuaW86ZGY4MTVlZTMtYjRiZi00MTE2LWFmN2MtMjczNWQ4YjA0YjY1' \
  -H 'cache-control: no-cache' \
  -H 'postman-token: cc209853-5c66-bfe5-487d-12b7883ba875'

AR: The response is still

{
    "data": {
        "id": "5aafca05d0516d0007758a26",
        "type": "execution-result",
        "links": {
            "self": "/v2/exec/result/5aafca05d0516d0007758a26"
        },
        "attributes": {
            "result": {
                "data": {
                    "available": "Available",
                    "pending": "Pending",
                    "sold": "Sold"
                }
            }
        }
    },
    "meta": {}
}

ER:

{
    "data": {},
    "meta": {}
}

remove member from Organisation documentation is incorrect

@khanzadyan commented on Fri Mar 09 2018

Documentation about removing a member from Organisation incorrectly states that tenantAdmin API Key must be used: https://api.elastic.io/v2/docs/#remove-member-from-organization

In reality, this action can be only be done by the Organisation Admin.

Сorrect the description of error codes

See the screen:

The JSON in curl for creating new SSH key is not valid

@HannaTrotsenko commented on Fri Dec 01 2017

STR:

1. Go to the https://api-sparrow.elastic.io/v2/docs/ and locate page for "Create a new SSH key"
2. Pay attention to the curl command

AR:

ER:

curl https://api.elastic.io/v2/sshkeys/ \
    -X POST \
    -u [email protected]:cbe86fbf-708b-4020-b7d6-09bfef3fc24f \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' -d '
    {
"data": {
        "type": "sshkey",
        "attributes": {
            "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDf0QiuqfcAMXK58vbHcS6DjPLk48ksR6xj/ApRF8GhzzEUtPdeqLEsf1MIJx61dd0E6UdmW4AIbwDcTOMWz0f+9Ue7AypkPwn+kt9y6JOdW+GC+f+2wJzR3ySgq8XGHwsHmANlegZIlzyFGqm4YbGdxqTtBENrJZGQpayGMcI72662HxAsCrAoENyCLPml+lWr6cYaK7r0WLEmoZefzuLgO3VMVIaGK9B+5unQ0R2UMozwJJutYTCJAlnTIvO3BceHcrNnEAjYuvx1khdNd3+4Mrs/Q1LTzavqVy/Ot9ZpK3xah4bnFHbcunVzlCeiY5HLTfrcSgmsa9xhgj+viMJj hanna@hanna-UX430UQ",
           "title": "My New Key"
         }
    }
}'

The wrong access permission for "Create a user"

Preconditions

API docs say:

AUTHORIZATION
This request is authorized to only a user with TenantAdmin role (contact support to get this role).

STR:

1. Create request with Organization API key

AR:

{
    "data": {
        "id": "5aabc258bd6d6400079b4592",
        "type": "user",
        "links": {
            "self": "/v2/users/5aabc258bd6d6400079b4592"
        },
        "attributes": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "[email protected]",
            "company": "Doe & Partners",
            "registered": "2018-03-16T13:10:48.221Z",
            "last_login": "2018-03-16T13:10:48.221Z"
        }
    },
    "meta": {}
}

ER: an error about authorization

Using Tenant API key in request return the same response as above

Update api-docs: add information about access level for Components-requests

Update api-docs: add information about access level for Components-requests

• Retrieve components - all requests
• Update access level of the component

The JSON in curl for creating new environment variables is not valid

@HannaTrotsenko commented on Fri Jan 19 2018

AR:

curl https://api.elastic.io/v2/components/{COMPONENT_ID}/env \
   -X PUT
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
   -H 'Content-Type: application/json' -d '
   {
       "data": {
           "type": "component-env",
           "attributes": {
               "vars": {
                   "MY_ENV_VAR": "env_var_value"
               }
           }
       }
   }'

ER:

curl https://api-sparrow.elastic.io/v2/components/5a4f3e34cbe7940019697e87/env \
   -X PUT \
   -u [email protected]:df815ee3-b4bf-4116-af7c-2735d8b04b65 \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
       "data": {
           "type": "component-env",
           "attributes": {
               "vars": {
                   "": "EMPTY_env_var_value"
               }
           }
       }
   }'

The wrong access permission for "Retrieve a user by ID" (Organization Admin has access to any user in given Tenant))

Preconditions

API docs say:

AUTHORIZATION
This request is authorized to only a user with TenantAdmin role (contact support to get this role).

STR:

1. Create request with Organization API key

AR:

{
    "data": {
        "id": "59d3562c68ed850019bde27f",
        "type": "user",
        "links": {
            "self": "/v2/users/59d3562c68ed850019bde27f"
        },
        "attributes": {
            "first_name": "Oksana",
            "last_name": "Luzha",
            "email": "[email protected]",
            "company": "qaz",
            "registered": "2017-10-03T09:19:40.598Z",
            "last_login": "2018-03-16T10:30:38.656Z"
        }
    },
    "meta": {}
}

ER: an error about authorization

Using Tenant API key in request return the same response as above

Change object to array in all endpoints which use role

• v2/workspaces/:id/members
• /v2/workspaces/:id/members/:id
• /v2/contracts/:id/members/
• /v2/contracts/:id/invites

Create a flow: total update of cUrl

I think cUrl for creating flow is too ancient:

curl https://api.elastic.io/v2/flows \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
      "data": {
        "type": "flow",
        "attributes": {
          "name": "Timer to E-Mail",
          "type": "ordinary",
          "graph": {
            "nodes": [
              {
                "id": "step_1",
                "command": "elasticio/timer:timer",
                "fields": {
                  "interval": "minute"
                }
              },
              {
                "id": "step_2",
                "command": "elasticio/email:send"
              }
            ],
            "edges": [
              {
                "source": "step_1",
                "target": "step_2",
                "config": {
                  "mapper": {
                    "to": "[email protected]",
                    "subject": "Test",
                    "textBody": "{{fireTime}}"
                  }
                }
              }
            ]
          }
        }
      }
    }'

Retrieve a credential by ID: incorrect information in the doc

In the doc: This resource allows you to retrieve a credential by its identifier. If the credential with given ID does not belong to the current user an error is returned.
BUT in real: user can receive information about the credential, which belongs another user

Add information about list of service account permissions

We should provide a list of permission that belongs to service accounts at docs/v2/#tenants section

The wrong access permission for "Remove member from organization"

Preconditions

API docs say:

AUTHORIZATION
This request is authorized to only a user with TenantAdmin role (contact support to get this role).

STR:

1. Create request with Organization API key

AR:

{
    "data": {},
    "meta": {}
}

ER: an error about authorization

Using Tenant API key in request return 403

{
    "errors": [
        {
            "status": 403,
            "title": "Error",
            "detail": "You cannot access this resource"
        }
    ]
}

Retrieve a component by ID: wrong information in the description

See the screen

The wrong access permission for "Delete a user"

Preconditions

API docs say:

AUTHORIZATION
This request is authorized to only a user with TenantAdmin role (contact support to get this role).

STR:

1. Create request with Organization API key

AR:

204 No Content

ER: an error about authorization

Using Tenant API key in request return the same response as above

The result of cURL for Retrieve of flows is not equal API documentation Example Response

@HannaTrotsenko commented on Mon Mar 12 2018

STR:

1. Use the next cURL for retrieving flows with parameters

curl 'https://api-sparrow.elastic.io/v2/flows?filter[status]=active&filter[user]=59d22e7eeb865b0018adc248&filter[type]=ordinary' \
   -g  -u [email protected]:a398e3fe-dc28-4d32-9a2d-2a55654468ce

The response in terminal is :

{
  "data": [
    {
      "id": "5aa683400581b5000739c192",
      "type": "flow",
      "links": {
        "self": "/v2/flows/5aa683400581b5000739c192"
      },
      "attributes": {
        "api_version": "2.0",
        "created_at": "2018-03-12T13:40:16.090Z",
        "current_status": "active",
        "default_mapper_type": "jsonata",
        "description": null,
        "graph": {
          "nodes": [
            {
              "id": "step_1",
              "command": "elasticio/code:executeTrigger@latest",
              "name": "",
              "description": "",
              "fields": {
                "code": "// Please note only Node.js code is supported here\nconsole.log('Hello code, incoming message is msg=%j', msg);\n\n// Create message to be emitted\nvar data = messages.newMessageWithBody({message: 'hello world'});\n\n// Emit the data event\nemitter.emit('data', data);\n\n// No need to emit end\nconsole.log('Finished execution');"
              },
              "selected_data_samples": [
                "5aa6834c0581b5000739c193"
              ],
              "out_data_samples": [
                "5aa6834c0581b5000739c193"
              ]
            }
          ],
          "edges": []
        },
        "name": "active",
        "status": "active",
        "type": "ordinary",
        "updated_at": "2018-03-12T13:44:56.037Z"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "59d22e7eeb865b0018adc248",
            "type": "user"
          },
          "links": {
            "self": "/v2/users/59d22e7eeb865b0018adc248"
          }
        },
        "organization": {
          "data": {
            "id": "5aa681800581b5000739c190",
            "type": "organization"
          },
          "links": {
            "self": "/v2/organizations/5aa681800581b5000739c190"
          }
        },
        "versions": {
          "links": {
            "related": "/v2/flows/5aa683400581b5000739c192/versions"
          }
        },
        "latest_version": {
          "data": {
            "id": "12cf7376a34e34b2c4bcda3e35ae84cecc88519c",
            "type": "flow-version"
          },
          "links": {
            "self": "/v2/flows/5aa683400581b5000739c192/versions/12cf7376a34e34b2c4bcda3e35ae84cecc88519c",
            "related": "/v2/flows/5aa683400581b5000739c192/versions/12cf7376a34e34b2c4bcda3e35ae84cecc88519c"
          }
        }
      }
    },
}

The API docs

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "type": "flow",
            "id": "585918da586224001b96de89",
            "attributes": {
              "name": "Timer to E-Mail Test",
              "status": "inactive",
              "type": "ordinary",
              "graph": {
                "nodes": [
                  {
                    "id": "step_1",
                    "command": "elasticio/timer:timer",
                    "fields": {
                      "interval": "minute"
                    }
                  },
                  {
                    "id": "step_2",
                    "command": "elasticio/email:send"
                  }
                ],
                "edges": [
                  {
                    "source": "step_1",
                    "target": "step_2",
                    "config": {
                      "mapper": {
                        "to": "[email protected]",
                        "subject": "Test",
                        "textBody": "{{fireTime}}"
                      }
                    }
                  }
                ]
              }
            },
            "relationships": {
              "user": {
                "data": {
                  "type": "user",
                  "id": "560e5a27734d480a00000002"
                },
                "links": {
                  "self": "/v2/users/560e5a27734d480a00000002"
                }
              },
              "organization": {
                "data": {
                  "type": "organization",
                  "id": "573dd76962436c349f000003"
                },
                "links": {
                  "self": "/v2/organizations/573dd76962436c349f000003"
                }
              }
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }

}

What we have to do with "Lookup tables" in api-docs

Description

We have a section called Lookup tables at elastic.io/v2/docs.

The response to GET https://api-sparrow.elastic.io/v2/lookup is:

{
    "data": [],
    "meta": {}
}

So, do we need this section in docs?

Remove all the Node.js tabs and all the TBD examples

Almost every API resource has this TBD example for Node.js

API-Docs – add Contracts and Workspaces

Review the API docs

We found these two issues #88 and #89 reporting that our API docs are wrong. Please review the docs and test every single example.

Remove blank grey are after every Example of response

See the screen:

Create a page or a section about Delete

• Remove Member from Workspace
• Remove Member from Contract (see requirenments in desciption)
• Remove Workspace
• Remove Contract
• Remove User

Wrong information in the section "Components"

See the screen:

_tenants.md should also include rebranded information

  "header_logo_url":"//cdn.elastic.io/logo-mini.png",
  "loading_logo_url":"//cdn.elastic.io/logo-mini.png",
  "email_logo_url":"//cdn.elastic.io/logo-mini.png",
  "favicon_url":"//cdn.elastic.io/logo-mini.png",
  "terms_of_usage_url":"https://www.elastic.io/tou/",
  "privacy_policy_url":"https://www.elastic.io/privacy-policy/",
  "imprint_url":"https://www.elastic.io/legal-disclosure/",
   "documentation":"https://docs.elastic.io/"

Invalid name of param account for create-task

In the example of a task at https://api.elastic.io/docs/#create-task param named as account but actually, it doesn't work.

I've found, that it works with _account as param name.
So it would be very nice to update either docs or real name in API.

The inaccuracies at "Delete user" docs

Wrong API documentation about member invites

@zubairov commented on Wed Jan 10 2018

See this screenshot:

Difference is highlighted with the red arrows.

---

@khanzadyan commented on Wed Jan 10 2018

And this is the correct one: https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/invites/

Wrong description of the section "Retrieve all components"

See the screen:

We have a mismatches between response example in api-docs and real response

• update docs with actual example
• doc is updated

Retrieve your user

AR: The real response

{
    "data": {
        "id": "59d22e7eeb865b0018adc248",
        "type": "user",
        "links": {
            "self": "/v2/users/59d22e7eeb865b0018adc248"
        },
        "attributes": {
            "first_name": "Anna",
            "last_name": "Trotsenko",
            "email": "[email protected]",
            "company": "elastic.io",
            "registered": "2017-10-02T12:18:06.274Z",
            "last_login": "2018-03-15T16:53:57.696Z"
        }
    },
    "meta": {}
}

ER: Example Response

{
    "data": {
        "id": "54f4be3fe7d5224f91000001",
        "type": "user",
        "attributes": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "[email protected]"
        }
    }
}

Missing describe access permissions to request

• Retrive all components
• Create a component repository
• Create a credential
• Update a credential
• Delete a credential
• Create data sample
• Update data sample
• Create a flow
• Create a team
• Add a new member to a team
• Remove a member from a team
• Delete a team

The inaccuracies at "Delete a team" docs

AR:

{
    "errors": [
        {
            "detail": "you cannot remove teams with repos, you should delete them first",
            "status": 409,
            "code": 409,
            "title": "Conflict",
            "meta": {}
        }
    ]
}

ER:

Retrieve data sample: wrong information in the doc

In the doc: User without organization can get only own samples.
But in the real: we don't have any user without organization

Retrieve component version: wrong information

See the screen:

Document /v2/flows last_modified sort

last_modified is sort by date of update with PUT /v2/flows

The JSON in cURL for "Create a user" is invalid

AR:

ER: Password in example should have at least 8 symbols

Update component access: improving the doc

To add information, that user can change the level of access just only in one case: from team to tenant

/v2/resources/storage/signed-url endpoint should be documented

This functionality is referenced in this article however it is not in the API documentation. We should add documentation for this endpoint.

Retrieve all credentials: wrong information in the doc

In the doc: This resource allows you to retrieve all credentials belonging to the given user.

AR: the user receives all credentials, belonging to all members of his organization

Invalid doc for create-task

https://api.elastic.io/docs/#create-task
It seems that param action has been renamed into function and description is outdated.

Resource /storage/signed-url is documented in API docs

https://github.com/elasticio/api/blob/master/v2/routes/resources/index.js#L15

Please see how a similar resource was documented in API v1. Note that in v1 the resource was called resources/s3/signed-url.