API Inventory

O API Inventory documenta suas APIs, descobrindo automaticamente endpoints. Saiba mais clicando aqui.

Serviços

Listar serviços

Lista todos os serviços da conta.

GET /v1/api-inventory/services

CURL

$ curl https://api.gocache.com.br/v1/api-inventory/services \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": [
    {
      "created_at": "1788287223",
      "baseUrls": [
        "https://meudominio.com"
      ],
      "id": "b4f54eff0629b483fe66f70bd8fc1830",
      "endpointCount": 19,
      "name": "Serviço de Exemplo",
      "description": "Serviço criado para documentar uma API.",
      "ignoredPaths": [
        "/.well-known"
      ]
    }
  ]
}

Baixar OpenAPI

O API Inventory documenta as APIs utilizando o padrão OpenAPI. É possível baixar o arquivo completo por este endpoint. Só é disponível a versão do arquivo em JSON.

GET /v1/api-inventory/services/{service_id}/download

CURL

$ curl https://api.gocache.com.br/v1/api-inventory/services/4d51b47d61b102fad553f0c4dfdc56d7/download \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "result": {
    "openapi": "3.2.0",
    "info": {
      "title": "Meu serviço",
      "description": "",
      "version": "0.0.1"
    },
    "servers": [
      {
        "url": "https://dominio.com"
      }
    ],
    "paths": {
      "/": {
        "get": {
          "responses": {
            "200": {
              "description": "OK"
            }
          },
          "x-autogenerated": true
        }
      }
    },
    "x-ignored-paths": []
  }
}

Criar serviço

Cria um serviço para documentar uma API.

POST /v1/api-inventory/services

CURL

$ curl -X POST https://api.gocache.com.br/v1/api-inventory/services \
-H "GoCache-Token: meu_token" -H "Content-Type: application/json"  \
-d '{"name": "Meu serviço", "description": "Documentando minha API", 
"baseUrls": ["https://meudominio.com/api"], "ignoredPaths": ["/api/v1"] }'

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": {
    "baseUrls": [
      "https://meudominio.com/api"
    ],
    "id": "57e644909ba6dc8da609e0d4f1f14b72",
    "endpointCount": 1,
    "name": "Meu serviço",
    "description": "Documentando minha API",
    "ignoredPaths": [
      "/api/v1"
    ]
  }
}

Parâmetros

Campo	Opcional	Tipo	Descrição
name		String	Nome do serviço
description	✓	String	Descrição do serviço
baseUrls		String[]	Trecho inicial da URL que o serviço possui
ignoredPaths	✓	String[]	Trecho inicial da URI que será ignorado neste serviço, útil para cenários específicos. Veja casos de uso clicando aqui

Editar serviço

Edita um serviço existente. Todos os campos são opcionais, e apenas será atualizado as informações enviadas.

PATCH /v1/api-inventory/services/{service_id}

CURL

$ curl -X POST https://api.gocache.com.br/v1/api-inventory/services/57e644909ba6dc8da609e0d4f1f14b72 \
-H "GoCache-Token: meu_token" -H "Content-Type: application/json"  \
-d '{"description": "Minha nova descrição"}'

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": {
    "baseUrls": [
      "https://meudominio.com/api"
    ],
    "id": "57e644909ba6dc8da609e0d4f1f14b72",
    "endpointCount": 1,
    "name": "Meu serviço",
    "description": "Minha nova descrição",
    "ignoredPaths": [
      "/api/v1"
    ]
  }
}

Parâmetros

Campo	Opcional	Tipo	Descrição
name	✓	String	Nome do serviço
description	✓	String	Descrição do serviço
baseUrls	✓	String[]	Trecho inicial da URL que o serviço possui
ignoredPaths	✓	String[]	Trecho inicial da URI que será ignorado neste serviço, útil para cenários específicos. Veja casos de uso clicando aqui

Excluir serviço

Deleta um serviço específico.

DELETE /v1/api-inventory/services/{service_id}

CURL

$ curl -X DELETE https://api.gocache.com.br/v1/api-inventory/services/57e644909ba6dc8da609e0d4f1f14b72 \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": "57e644909ba6dc8da609e0d4f1f14b72"
}

Importar OpenAPI

No API Inventory, salvamos os serviços como arquivos OpenAPI. É possível criar e atualizar serviços importando seus próprios arquivos OpenAPI, facilitando a integração com a plataforma.

Criar serviços

Este endpoint permite a criação de diversos serviços, realizando o upload de diferentes arquivos OpenAPI. Cada arquivo enviado gera um novo serviço.

POST /v1/api-inventory/services/import

CURL

$ curl -X POST https://api.gocache.com.br/v1/api-inventory/services/import \
-H "GoCache-Token: meu_token" -F "myfile=@openapi.yaml" -F "otherfile=@second_openapi.json"

O upload de arquivos deve ser realizado utilizando o encoding multipart/form-data.

Exemplo de sucesso

HTTP/1.1 202 Accepted
{
  "status_code": 1,
  "response": [
    {
      "taskId": "d867816a49264479c28b8924434acd85",
      "status": "waiting"
    },
    {
      "taskId": "d867816a49264479c28b8924434acd85",
      "status": "waiting"
    }
  ]
}

Processo assíncrono

O upload de arquivos OpenAPI para criação de serviços do API Inventory roda assincronamente. O resultado da chamada retorna a lista de arquivos que serão processados. O parâmetro taskId é igual para todos os arquivos importados na mesma chamada.

Listar estado da importação

Este endpoint retorna as informações de todos os arquivos OpenAPI enviados para importação e criação de serviços. Como a importação é assíncrona, recomendamos consultar este endpoint periodicamente (polling) para acompanhar o status da importação.

GET /v1/api-inventory/task/status/{task_id}

CURL

$ curl https://api.gocache.com.br/v1/api-inventory/task/status/d867816a49264479c28b8924434acd85 \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "result": [
    {
      "error": "Failed to validate OpenAPI document: Error: Document does not pass validation, Reason: OpenAPI document is not valid according to the 3.2.0 specification, Validation Errors: [Reason: validation failed, FieldPath: $.paths['~1store~1order~1search'].query.invalidInfo], Line: 1499, Column: 27. \n",
      "completed": true,
      "name": "myfile",
      "status": "error",
      "file": "openapi.yaml"
    },
    {
      "completed": true,
      "id": "920e2431ffb89bf1f84e4b82384a9bbe",
      "service": {
        "baseUrls": [
          "https://meudominio.com"
        ],
        "id": "920e2431ffb89bf1f84e4b82384a9bbe",
        "endpointCount": 4,
        "name": "Serviço Teste",
        "description": "",
        "ignoredPaths": []
      },
      "name": "otherfile",
      "status": "success",
      "file": "second_openapi.json"
    }
  ]
}

O processo de importação finaliza quando todos os arquivos retornam "completed": true.

Atualizar serviço

Visando facilitar integrações, é possível editar um serviço específico realizando o upload de um arquivo OpenAPI. O endpoint usado para atualização é o mesmo da criação de serviços por importação, mas deve-se enviar a query string service_id, com o ID do serviço que deve ser atualizado.

Diferente da criação, a atualização permite apenas o upload de um arquivo por vez. Além disso, o processo roda sincronamente. A requisição pode demorar alguns segundos enquanto realizamos as validações da especificação OpenAPI, e também a fusão dos arquivos.

O processo de atualização, por padrão, não sobrescreve o arquivo antigo com o arquivo enviado. Para evitar que informações descobertas pelo API Inventory sejam perdidas com atualizações, realizamos uma fusão inteligente dos arquivos para garantir que informações descobertas pela GoCache não sejam perdidas. O retorno desse endpoint é um resumo do processo de fusão. Ao utilizar este endpoint, a versão antiga do serviço é salva em um backup para facilitar o rollback em caso de problemas.

Modo estrito de fusão

Se você confia no conteúdo do novo arquivo e quer que ele substitua o arquivo anterior na atualização, é possível ativar o modo estrito de fusão, enviando a query string strict=true. Nesse cenário, a GoCache substituirá o arquivo antigo pelo conteúdo do novo.

As configurações do API Firewall, porém, são preservadas: se o novo arquivo não informar o campo x-firewall-action nos métodos, a configuração definida no arquivo antigo é mantida. Caso o campo seja enviado, o valor do novo arquivo prevalece.

POST /v1/api-inventory/services/import?service_id={service_id}&strict={false|true}

CURL

$ curl -X POST https://api.gocache.com.br/v1/api-inventory/services/import?service_id=920e2431ffb89bf1f84e4b82384a9bbe \
-H "GoCache-Token: meu_token" -F "file=@second_openapi_v2.json"

O upload do arquivo deve ser realizado utilizando o encoding multipart/form-data.

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": {
    "preserved": [
      {
        "pointer": "/paths/~1meu-path",
        "rule": "paths"
      }
    ],
    "id": "920e2431ffb89bf1f84e4b82384a9bbe",
    "replaced": [
      {
        "pointer": "/info",
        "reason": "no_discovery_domain"
      }
    ],
    "added": [
      {
        "pointer": "/paths/~1new-path",
        "rule": "paths"
      }
    ],
    "refs": {
      "truncated": false,
      "restored": [],
      "dangling": []
    },
    "conflicts": [],
    "stats": {
      "added": 1,
      "preserved": 1,
      "replaced": 1,
      "conflicts": 0,
      "refs_restored": 0
    }
  }
}

Rollback de atualização

Este endpoint permite voltar o serviço para a última versão antes de uma atualização através da importação de arquivo OpenAPI. Sempre que um serviço é atualizado através do upload de um arquivo, a versão antiga é salva em um backup.

POST /v1/api-inventory/services/{service_id}/rollback

CURL

$ curl -X POST https://api.gocache.com.br/v1/api-inventory/services/920e2431ffb89bf1f84e4b82384a9bbe/rollback \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 204 No Content

Rollback único

O rollback só está disponível para endpoints que realizaram uma atualização através de importação de arquivo. Após realizar o rollback, a versão antiga do arquivo pré-atualização é restaurada, e o backup excluído. Por isso, esse endpoint só pode ser chamado uma vez após cada atualização. Cada atualização sobrescreve o backup com a versão atual de produção.

Endpoints

Listar endpoints

Este endpoint serve para visualizar um resumo de todos os endpoints de um serviço.

GET /v1/api-inventory/services/{service_id}/endpoints

CURL

$ curl https://api.gocache.com.br/v1/api-inventory/services/b4f54eff0629b483fe66f70bd8fc1830/endpoints \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": [
    {
      "path": "/",
      "id": "R0VUOi8=",
      "method": "GET",
      "autogenerated": true,
      "firewall_action": "accept",
      "trust_level": 100
    }
  ]
}

Criar endpoint

A criação de endpoints permite adicionar endpoints sem definir a estrutura de corpo e parâmetros de query string ou headers.

POST /v1/api-inventory/services/{service_id}/endpoints

CURL

$ curl -X POST https://api.gocache.com.br/v1/api-inventory/services/4d51b47d61b102fad553f0c4dfdc56d7/endpoints \
-H "GoCache-Token: meu_token" -H "Content-Type: application/json"  \
-d '{"path": ["/users", "/users/{user_id}"], "method": ["GET", "POST", "QUERY"], 
"firewall_action": "accept" }'

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": {
    "result": [
      {
        "path": "/users",
        "id": "UVVFUlk6L3VzZXJz",
        "method": "QUERY",
        "serviceId": "4d51b47d61b102fad553f0c4dfdc56d7",
        "firewall_action": "accept"
      },
      {
        "path": "/users/{user_id}",
        "id": "UVVFUlk6L3VzZXJzL3t1c2VyX2lkfQ==",
        "method": "QUERY",
        "serviceId": "4d51b47d61b102fad553f0c4dfdc56d7",
        "firewall_action": "accept"
      },
      {
        "path": "/users",
        "id": "UE9TVDovdXNlcnM=",
        "method": "POST",
        "serviceId": "4d51b47d61b102fad553f0c4dfdc56d7",
        "firewall_action": "accept"
      },
      {
        "path": "/users/{user_id}",
        "id": "UE9TVDovdXNlcnMve3VzZXJfaWR9",
        "method": "POST",
        "serviceId": "4d51b47d61b102fad553f0c4dfdc56d7",
        "firewall_action": "accept"
      },
      {
        "path": "/users",
        "id": "R0VUOi91c2Vycw==",
        "method": "GET",
        "serviceId": "4d51b47d61b102fad553f0c4dfdc56d7",
        "firewall_action": "accept"
      },
      {
        "path": "/users/{user_id}",
        "id": "R0VUOi91c2Vycy97dXNlcl9pZH0=",
        "method": "GET",
        "serviceId": "4d51b47d61b102fad553f0c4dfdc56d7",
        "firewall_action": "accept"
      }
    ],
    "errors": []
  }
}

Parâmetros

Campo	Opcional	Tipo	Descrição
path		String[]	Lista de paths a serem criados
method		String[]	Lista de métodos a serem criados para cada path enviado
firewall_action	✓	String	Ação do API Firewall para os endpoints criados. Por padrão os endpoints são criados com a ação accept. Possíveis valores: accept, simulate e block

Editar API Firewall

Este endpoint edita a ação do API Firewall para múltiplos endpoints.

PATCH /v1/api-inventory/services/{service_id}/endpoints

CURL

$ curl -X PATCH https://api.gocache.com.br/v1/api-inventory/services/4d51b47d61b102fad553f0c4dfdc56d7/endpoints \
-H "GoCache-Token: meu_token" -H "Content-Type: application/json"  \
-d '{"endpoints": ["R0VUOi91c2Vycy97dXNlcl9pZH0=", "UE9TVDovdXNlcnMve3VzZXJfaWR9"], "firewall_action": "simulate" }'

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": {
    "result": [
      {
        "firewall_action": "simulate",
        "id": "R0VUOi91c2Vycy97dXNlcl9pZH0="
      },
      {
        "firewall_action": "simulate",
        "id": "UE9TVDovdXNlcnMve3VzZXJfaWR9"
      }
    ],
    "errors": []
  }
}

Parâmetros

Campo	Opcional	Tipo	Descrição
endpoints		String[]	Lista de ID de endpoints que terão a ação do API Firewall atualizada.
firewall_action		String	Ação do API Firewall que será atualizado em todos endpoints encaminhados. Possíveis valores: accept, simulate e block

Editar parâmetros de endpoint

Este endpoint permite atualizar os parâmetros de um endpoint. Atualmente os parâmetros possíveis de serem editados são: requestBody, security e parameters. Apenas os campos enviados são atualizados, os não enviados são ignorados.

É possível deletar um campo definindo seu valor para null. Para o requestBody, apenas os content-types enviados dentro de content são atualizados. Se não for enviado um content-type, ele será ignorado na atualização.

Os campos devem seguir o padrão OpenAPI para serem considerados válidos.

PATCH /v1/api-inventory/services/{service_id}/endpoints/{endpoint_id}

CURL

$ curl -X PATCH https://api.gocache.com.br/v1/api-inventory/services/4d51b47d61b102fad553f0c4dfdc56d7/endpoints/UE9TVDovdXNlcnMve3VzZXJfaWR9 \
-H "GoCache-Token: meu_token" -H "Content-Type: application/json"  \
-d '{"requestBody": {"content": {"application/json": {"schema": {}}}}}'

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": {
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "parameters": [
      {
        "in": "path",
        "name": "user_id",
        "schema": {
          "type": "string"
        },
        "required": true
      }
    ]
  }
}

Parâmetros

Campo	Opcional	Tipo	Descrição
requestBody	✓	Object	Campo requestBody seguindo os padrões OpenAPI do endpoint
security	✓	Object	Campo security seguindo os padrões OpenAPI do endpoint
parameters	✓	Object	Campo parameters seguindo os padrões OpenAPI do endpoint

Excluir endpoint

Deleta um endpoint específico.

DELETE /v1/api-inventory/services/{service_id}/endpoints/{endpoint_id}

CURL

$ curl -X DELETE https://api.gocache.com.br/v1/api-inventory/services/4d51b47d61b102fad553f0c4dfdc56d7/endpoints/UE9TVDovdXNlcnMve3VzZXJfaWR9 \
-H "GoCache-Token: meu_token"

Exemplo de sucesso

HTTP/1.1 200 OK
{
  "status_code": 1,
  "response": { "id": "UE9TVDovdXNlcnMve3VzZXJfaWR9" }
}