elasticio / api-docs Goto Github PK

View Code? Open in Web Editor NEW

2.0 10.0 1.0 1.29 MB

Docs for elastic.io API

Ruby 1.25% JavaScript 76.77% HTML 3.34% Dockerfile 1.41% SCSS 15.51% Shell 1.72%

api-docs's Introduction

Introduction

The docs are generated with Slate.

How to edit/add resources documentation to existing api docs?

Api-docs for api version 2 is placed at directory source.

All documented resources located in directories source_v{API_VER}/include. You can edit existing files there or create new files (resources).

How to create new api docs for new api version?

For example, you want to create docs for new api of version 15.

In api-docs root, create directory called source_15 and add there Slate initial files (or copy/paste from some another source_{API_VER} directory)
In ./.nginx/.conf add new location directive inside server directive:

location /api-v15 {
    alias /usr/src/app/build_v15;
}

Add these commands at the end of RUN command at image of dependencies at ./Dockerfile:

cp -a ./source_v15 ./source && \
bundle exec middleman build && \
rm -rf ./source && \
rm -rf ./build_v15 && \
mv ./build ./build_v15

Add this command to the list of COPY commands at image of release at ./Dockerfile:

COPY --from=dependencies /usr/src/app/build_v15 ./build_v15

(replace v15 with your api version)

How to customize api docs for a special customer?

In case the api-docs have to be "re-branded" for a special customer, there are a few build-arguments which point by default to elastic.io original values:

toc_footer: The text or HTML-Fragment displayed at the bottom of the Table of Contents (default: Link to sign-up for a developer key)
api_base_url: Url of the customers API (default: https://api.elastic.io)
product_name: Name of this API product (default: elastic.io)
logo_url: URL to refer the customers logo (default: https://app.elastic.io/img/logo.svg)
repo_name: Name of github repository name (default: elasticio)
docs_url: Link to the main documentation (default: http://docs.elastic.io/docs)
favicon_url: Link to the favicon (default: https://app.elastic.io/favicon.ico)

So a complete build for a customer overwriting everything may be e.g.:

docker build -t apidocs:telekom \
        --build-arg "toc_footer=Some Footer Text" \
        --build-arg "api_base_url=http://api.customer.org" \
        --build-arg "product_name=Customer API Name" \
        --build-arg "logo_url=https://customer.logo.url/svg-image.svg" \
        --build-arg "repo_name=customer-repo" \
        --build-arg "favicon_url=https://favicon.url/favicon.ico"
        .

How to check, what is in the `master`

Run the api-docs:

docker run --rm -p 8000:8000 -d elasticio/api-docs:master

Open in your browser: http://localhost:8000/
Ensure that everything is ok.
Stop the api-docs:

docker stop api-doc-master

All docker builds could be checked here.

How to build and see api-docs static website locally?

1. Using Docker

Build docker image:

docker build -t api-docs .

Run container of newly built docker image (for example, at port 8081)

docker run --rm -p 8081:8000 -d api-docs

Access docs for api version at localhost:8081

2. "Manually"

Install required tools

apt-get update && \
    apt-get install -y ruby rubygems ruby-dev build-essential && \
    gem install bundler && \
    bundle install

Create directory source and paste there files from source_{SOME_API_VER}
Run
```
bundle exec middleman build
```

This command will create directory build with static website files.

Open build/index.html in browser

api-docs's People

Contributors

Stargazers

Watchers

Forkers

thatapp

api-docs's Issues

Wrong information in the section "Components"

See the screen:

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.

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:

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

/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.

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:

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

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

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:

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"
        }
    ]
}

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/

Missing describe access permissions to request

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

STR:

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"
                }
            }
        }
    }
 }'

Copy the "id" from response
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": {}
}

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

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:

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

Сorrect the description of error codes

See the screen:

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

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

STR:

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

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:

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

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]"
        }
    }
}

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

AR:

ER: Password in example should have at least 8 symbols

_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/"

Retrieve component version: wrong information

See the screen:

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

@HannaTrotsenko commented on Mon Mar 12 2018

STR:

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
    }

}

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.

Create a page or a section about Delete

Document /v2/flows last_modified sort

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

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.

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

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

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.

Wrong description of the section "Retrieve all components"

See the screen:

POST /v2/workspaces is located under Contracts

Which is wrong

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

API docs describe the not-existing feature

api docs

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 JSON in curl for creating new SSH key is not valid

@HannaTrotsenko commented on Fri Dec 01 2017

STR:

Go to the https://api-sparrow.elastic.io/v2/docs/ and locate page for "Create a new SSH key"
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"
         }
    }
}'

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

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"
               }
           }
       }
   }'

API-Docs – add Contracts and Workspaces

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

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

Retrieve a component by ID: wrong information in the description

See the screen

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

Retrieve components - all requests
Update access level of the component

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.

The inaccuracies at "Delete user" docs

Remove blank grey are after every Example of response

See the screen:

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

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.

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}}"
                  }
                }
              }
            ]
          }
        }
      }
    }'

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:

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

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?

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.

elasticio / api-docs Goto Github PK

api-docs's Introduction

Introduction

How to edit/add resources documentation to existing api docs?

How to create new api docs for new api version?

How to customize api docs for a special customer?

How to check, what is in the master

How to build and see api-docs static website locally?

1. Using Docker

2. "Manually"

api-docs's People

Contributors

Stargazers

Watchers

Forkers

api-docs's Issues

Preconditions

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

Preconditions

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

Preconditions

Using Tenant API key in request return 403

Preconditions

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

Retrieve your user

STR:

The response in terminal is :

The API docs

Preconditions

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

Description

Recommend Projects

Recommend Topics

Recommend Org

How to check, what is in the `master`

`Retrieve your user`