Por Alexandre Lumertz em 9 de novembro de 2023

Principiante

API REST

A estrutura IVY gera API REST para todos os seus DocTypes prontos para uso. Você também pode executar métodos python arbitrários usando o caminho do módulo pontilhado.

Autenticação_

Existem duas maneiras de autenticar através da API REST do IVY. Autenticação baseada em token e autenticação baseada em senha.

1. Autenticação baseada em token_

Um token é um par de chave de API e segredo de API. Para gerar esses tokens siga estas etapas:

Vá para a lista de usuários e abra um usuário.
Clique na guia "Configurações". (pule esta etapa se você não vir as guias)
Expanda a seção Acesso à API e clique em Gerar chaves.
Você receberá um pop-up com o segredo da API. Copie este valor e guarde-o em algum lugar seguro (Gerenciador de Senhas).
Você também verá outro campo “Chave de API” nesta seção.

O token é gerado concatenando api_keye api_secretcom dois pontos :. Passe a string token api_key:api_secretpara o Authorizationcabeçalho da solicitação.

fetch('http://<base-url>/api/method/frappe.auth.get_logged_user', {
  headers: {
    'Authorization': 'token api_key:api_secret'
  }
})
.then(r => r.json())
.then(r => {
  console.log(r);
})

➜ curl http://<base-url>/api/method/frappe.auth.get_logged_user -H "Authorization: token api_key:api_secret"

Cada solicitação feita com esses tokens será registrada no usuário selecionado na Etapa 1. Isso também significa que as funções serão verificadas nesse usuário. Você também pode criar um novo usuário apenas para chamadas de API.

2. Autenticação baseada em senha_

A autenticação baseada em senha depende de cookies e dados de sessão para manter a autenticação em solicitações subsequentes. Na maioria dos casos, a biblioteca que você está usando para emitir chamadas REST manipulará os dados da sessão, mas se isso não acontecer, você deverá usar a autenticação baseada em token.

fetch('http://<base-url>/api/method/login', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },body: JSON.stringify({
    usr: 'username or email',
    pwd: 'password'
  })
})
.then(r => r.json())
.then(r => {
  console.log(r);
})

➜ curl --cookie-jar snowcookie --request POST "http://<base-url>/api/method/login" -H 'Content-Type: application/json' -H 'Accept: application/json' --data-raw "{ \"usr\" : \"<username>\", \"pwd\": \"<password>\" }"

{"message":"Logged In","home_page":"/app","full_name":"<user:full_name>","dashboard_route":"/sites"}

➜ curl --cookie snowcookie --request POST "http://<base-url>/api/method/frappe.auth.get_logged_user" -H 'Accept: application/json'

{"message":"<username>"}

3. Token de acesso_

Consulte a documentação sobre.

Use o access_tokencabeçalho da solicitação gerado.

fetch('http://<base-url>/api/method/frappe.auth.get_logged_user', {
  headers: {
    'Authorization': 'Bearer access_token'
  }
})
.then(r => r.json())
.then(r => {
  console.log(r);
})

Listagem de documentos_

Para obter uma lista de registros de um DocType, envie uma solicitação GET em /api/resource/:doctype. Por padrão, ele retornará 20 registros e buscará apenas o nome dos registros. O resultado da consulta pode ser encontrado datana carga útil.

Usaremos o ToDo DocType para mostrar exemplos de respostas para as consultas abaixo.

GET /api/resource/:doctype

Resposta

{
 "data":[
  {"name":"f765eef382"},
  {"name":"2a26fa1c64"},
  {"name":"f32c68060f"},
  {"name":"9065fa9832"},
  {"name":"419082fc38"},
  {"name":"6234d15099"},
  {"name":"62f2181ee0"},
  {"name":"a50afbbfaa"},
  ...
 ]
}

Você pode especificar quais campos buscar no fieldsparâmetro. Deve ser uma matriz JSON.

GET /api/resource/:doctype?fields=["field1", "field2"]

Resposta

{
 "data":[
  {"description":"Business worker talk society. Each try theory prove notice middle. Crime couple trouble guy project hit.","name":"f765eef382"},
  {"description":"This reveal as look near sister. Car staff bar specific address.","name":"2a26fa1c64"},
  {"description":"Wear bag some walk. Movie partner new class tough run. Brother Democrat imagine.","name":"f32c68060f"},
  {"description":"Break laugh apply reveal new now focus heavy. Outside local staff research total. Else point try despite.","name":"9065fa9832"},
  {"description":"Truth reduce baby artist actually model. Cost phone us others himself wife almost. Language thing wonder share talk. Factor glass significant could window certain yet.","name":"419082fc38"},
  {"description":"Tv memory understand opportunity window beat physical.","name":"6234d15099"},
  {"description":"Should floor situation in response sell. Our assume company mean red majority shoulder.","name":"62f2181ee0"},
  {"description":"Performance seem sign recent. Court form me tonight simple trouble. Address job garden play teach. Happy speech amount offer change then.","name":"a50afbbfaa"},
  ...
 ]
}

Você pode filtrar os registros passando filterso parâmetro. Os filtros devem ser uma matriz, onde cada filtro tem o formato:[field, operator, value]

GET /api/resource/:doctype?filters=[["field1", "=", "value1"], ["field2", ">", "value2"]]

Resposta

{
 "data":[
  {"name":"f765eef382"},
  {"name":"2a26fa1c64"},
  {"name":"f32c68060f"},
  {"name":"9065fa9832"},
  {"name":"419082fc38"},
  {"name":"6234d15099"},
  {"name":"62f2181ee0"},
  {"name":"a50afbbfaa"},
  ...
 ]
}

filtersparâmetro une todos os filtros especificados usando ANDo operador SQL, se você quiser ORfiltros você pode usar o or_filtersparâmetro. A sintaxe para or_filtersé igual a `filtros.

Você também pode fornecer o campo de classificação e a ordem. Deve estar no formato fieldname ascou fieldname desc. O espaço deve ser codificado em URL. Na linha a seguir, consideramos fieldname como title.

GET /api/resource/:doctype?order_by=title%20desc

Você também pode paginar os resultados fornecendo os parâmetros limit_starte limit_page_length.

GET /api/resource/:doctype?limit_start=5&limit_page_length=10

Resposta

{
 "data": [
  {"name":"6234d15099"},
  {"name":"62f2181ee0"},
  {"name":"a50afbbfaa"},
  {"name":"aa12a5cf71"},
  {"name":"6ac9800d4e"},
  {"name":"4bcf8b701c"},
  {"name":"aee15f4c20"},
  {"name":"6ba753afef"},
  ...
 ]
}

limité um alias para limit_page_lengthacesso /api/resourcena versão 13. Isso significa que o seguinte também deve retornar a mesma carga útil da consulta acima.

GET /api/resource/:doctype?limit_start=5&limit=10

Por padrão, você receberá os dados como arquivos List[dict]. Você pode recuperar seus dados List[List]passando as_dict=False.

GET /api/resource/:doctype?limit_start=5&limit=5&as_dict=False

Resposta

{
 "data": [
  ["6234d15099"],
  ["62f2181ee0"],
  ["a50afbbfaa"],
  ["aa12a5cf71"],
  ["6ac9800d4e"]
 ]
}

Para depurar a consulta criada para suas solicitações, você pode passar debug=Truecom a solicitação. Isso retorna a consulta executada e o tempo de execução excda carga útil.

GET /api/resource/:doctype?limit_start=10&limit=5&debug=True

Resposta

{
 "data": [
  {"name":"4bcf8b701c"},
  {"name":"aee15f4c20"},
  {"name":"6ba753afef"},
  {"name":"f4b7e24abc"},
  {"name":"bd9156096c"}
 ],"exc": "[\"select `tabToDo`.`name`\\n\\t\\t\\tfrom `tabToDo`\\n\\t\\t\\t\\n\\t\\t\\t\\n\\t\\t\\t order by `tabToDo`.`modified` DESC\\n\\t\\t\\tlimit 5 offset 10\", \"Execution time: 0.0 sec\"]"
}

Operações CRUD_

IVY gera endpoints REST para operações CRUD para todos os DocTypes automaticamente. Certifique-se de definir os seguintes cabeçalhos em suas solicitações para obter respostas JSON adequadas.

{
  "Accept": "application/json",
  "Content-Type": "application/json",
}

Criar_

Crie um novo documento enviando uma POSTsolicitação para /api/resource/:doctype. Envie o documento como JSON no corpo da solicitação.

POST /api/resource/:doctype# Body

{"description": "New ToDo"}

Resposta

{
 "data": {
  "name": "af2e2d0e33",
  "owner": "Administrator",
  "creation": "2019-06-03 14:19:00.281026",
  "modified": "2019-06-03 14:19:00.281026",
  "modified_by": "Administrator",
  "idx": 0,
  "docstatus": 0,
  "status": "Open",
  "priority": "Medium",
  "description": "New ToDo",
  "doctype": "ToDo"
 }
}

Ler_

Obtenha um documento enviando uma GETsolicitação para /api/resource/:doctype/:name.

GET /api/resource/:doctype/:name

Resposta

{
 "data": {
  "name": "bf2e760e13",
  "owner": "Administrator",
  "creation": "2019-06-03 14:19:00.281026",
  "modified": "2019-06-03 14:19:00.281026",
  "modified_by": "Administrator",
  "idx": 0,
  "docstatus": 0,
  "status": "Open",
  "priority": "Medium",
  "description": "<p>Test description</p>",
  "doctype": "ToDo"
 }
}

Atualizar_

Atualize um documento enviando uma PUTsolicitação para /api/resource/:doctype/:name. Você não precisa enviar o documento inteiro, basta enviar os campos que deseja atualizar.

PUT /api/resource/:doctype/:name# Body

{"description": "New description"}

Resposta

{
 "data": {
  "name": "bf2e760e13",
  "owner": "Administrator",
  "creation": "2019-06-03 14:19:00.281026",
  "modified": "2019-06-03 14:21:00.785117",
  "modified_by": "Administrator",
  "idx": 0,
  "docstatus": 0,
  "status": "Open",
  "priority": "Medium",
  "description": "New description",
  "doctype": "ToDo"
 }
}

Excluir_

Exclua um documento enviando uma DELETEsolicitação para /api/resource/:doctype/:name.

DELETE /api/resource/:doctype/:name

Resposta

{"message": "ok"}

Chamadas de método remoto_

IVY permite acionar métodos python arbitrários usando a API REST para lidar com lógica personalizada. Esses métodos devem ser marcados como permitidos para torná-los acessíveis via REST.

Para executar um método python na lista de permissões frappe.auth.get_logged_user, envie uma solicitação ao endpoint /api/method/frappe.auth.get_logged_user.

GET /api/method/frappe.auth.get_logged_user

Resposta

{
 "message": "john@doe.com"
}

Se o seu método retornar alguns valores, você deverá enviar uma GETsolicitação.
Se o seu método alterar o estado do banco de dados, use POST. Após uma POSTsolicitação bem-sucedida, a estrutura chamará automaticamente frappe.db.commit()para confirmar as alterações no banco de dados.
Uma resposta bem-sucedida retornará um objeto JSON com uma messagechave.
Uma resposta com erro retornará um objeto JSON com excchave que contém o rastreamento de pilha e exc_typeque contém a exceção lançada.
O valor de retorno do método será convertido em JSON e enviado como resposta.

Uploads de arquivos_

Existe um método dedicado /api/method/upload_fileque aceita dados de arquivos binários e os carrega no sistema.

Aqui está o comando curl para isso:

➜ curl -X POST \

http://<base-url>/api/method/upload_file \

-H 'Accept: application/json' \

-H 'Authorization: token xxxx:yyyy' \

-F file=@/path/to/file/file.png

Se você estiver usando Javascript do lado do cliente para fazer upload de arquivos, poderá anexar os arquivos carregados como FormData e enviar uma solicitação XHR.

Mais artigos sobre Recursos

API REST

Por Alexandre Lumertz em 9 de novembro de 2023

API REST

Autenticação_

﻿1. Autenticação baseada em token_

2. Autenticação baseada em senha_

3. Token de acesso_

Listagem de documentos_

Operações CRUD_

Criar_

Ler_

Atualizar_

﻿Excluir_

Chamadas de método remoto_

Uploads de arquivos_

Comentários

1. Autenticação baseada em token_

Excluir_