json - posts - wp rest api params




Formato de resposta da JSON API padrão? (9)

Existem normas ou práticas recomendadas para estruturar respostas JSON de uma API? Obviamente, todos os dados de um aplicativo são diferentes, de modo que eu não me preocupo com isso, mas sim com o "boilerplate de respostas", se você quiser. Um exemplo do que quero dizer:

Pedido de sucesso:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Pedido falhado:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Guia do Google JSON

data retorno da resposta de sucesso

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Erro de retorno da resposta de error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

e se o seu cliente for JS, você pode usar if ("error" in response) {} para verificar se há algum erro.


A seguir está o formato json que o instagram está usando

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

Eu fiz uma pequena pesquisa e descobri que o formato mais comum para retornar erro (exceções) é uma estrutura deste formulário:

{
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Este é o formato proposto pelo padrão de dados OASIS OASIS OData e parece ser a opção mais padrão por aí, no entanto, não parece haver altas taxas de adoção de qualquer padrão neste momento. Este formato é consistente com a especificação JSON-RPC.

Você pode encontrar a biblioteca completa de código aberto que implementa isso em: Mendocino JSON Utilities . Esta biblioteca suporta os Objetos JSON, bem como as exceções.

Os detalhes são discutidos na postagem do meu blog sobre tratamento de erros na API REST do JSON


Eu não serei tão arrogante para afirmar que este é um padrão, então vou usar o formulário "eu prefiro".

Eu prefiro uma resposta sucinta (ao solicitar uma lista de / articles eu quero um array JSON de artigos).

Nos meus projetos eu uso HTTP para relatório de status, um 200 retorna apenas a carga útil.

400 retorna uma mensagem do que estava errado com o pedido:

{"message" : "Missing parameter: 'param'"}

Retorna 404 se o modelo / controler / URI não existir

Se houve erro com o processamento do meu lado, retornarei 501 com uma mensagem:

{"message" : "Could not connect to data store."}

Pelo que vi, algumas estruturas REST-ish tendem a ser ao longo destas linhas.

Fundamentação :

JSON deve ser um formato de carga útil , não é um protocolo de sessão. Toda a idéia de cargas úteis de sessão verbais vem do mundo XML / SOAP e de várias escolhas equivocadas que criaram esses designs inchados. Depois que percebemos que tudo era uma enorme dor de cabeça, o objetivo do REST / JSON era beijar e aderir ao HTTP. Eu não acho que há algo remotamente padrão no JSend e especialmente não no mais detalhado entre eles. XHR irá reagir à resposta HTTP, se você usar o jQuery para o seu AJAX (como a maioria faz) você pode usar callbacks try / catch and done() / fail() para capturar erros. Não consigo ver como o encapsulamento de relatórios de status no JSON é mais útil do que isso.


Não há acordo sobre os demais formatos de resposta de grandes gigantes de software - Google, Facebook, Twitter, Amazon e outros, embora muitos links tenham sido fornecidos nas respostas acima, onde algumas pessoas tentaram padronizar o formato de resposta.

Como as necessidades da API podem diferir, é muito difícil incluir todos e concordar com algum formato. Se você tem milhões de usuários usando sua API, por que você mudaria seu formato de resposta?

A seguir, minha opinião sobre o formato de resposta inspirado no Google, Twitter, Amazon e alguns posts na internet:

https://github.com/adnan-kamili/rest-api-response-format

Arquivo Swagger:

https://github.com/adnan-kamili/swagger-sample-template



Por que vale a pena fazer isso de forma diferente. Uma chamada bem-sucedida só tem os objetos JSON. Não preciso de um objeto JSON de nível superior que contenha um campo de sucesso indicando true e um campo de carga útil que tenha o objeto JSON. Acabei de retornar o objeto JSON apropriado com um 200 ou o que for apropriado no intervalo 200 para o status HTTP no cabeçalho.

No entanto, se houver um erro (algo na família 400), retornarei um objeto de erro JSON bem formado. Por exemplo, se o cliente estiver colocando um usuário em POST com um endereço de e-mail e número de telefone e um deles estiver malformado (ou seja, não puder inseri-lo em meu banco de dados subjacente), retornarei algo assim:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

Os bits importantes aqui são que a propriedade "field" deve corresponder exatamente ao campo JSON que não pôde ser validado. Isso permite que os clientes saibam exatamente o que deu errado com sua solicitação. Além disso, "message" está na localidade da solicitação. Se o "emailAddress" e "phoneNumber" forem inválidos, a matriz "errors" conterá entradas para ambos. Um corpo de resposta do JSON 409 (Conflito) pode ter esta aparência:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

Com o código de status HTTP e este JSON, o cliente tem tudo o que precisa para responder aos erros de maneira determinística e não cria um novo padrão de erro que tente completar os códigos de status HTTP. Observe que isso ocorre apenas no intervalo de 400 erros. Para qualquer coisa na faixa de 200, posso simplesmente retornar o que for apropriado. Para mim, é frequentemente um objeto JSON parecido com HAL, mas isso não importa realmente aqui.

A única coisa que pensei em adicionar foi um código de erro numérico nas entradas de matriz "errors" ou na raiz do próprio objeto JSON. Mas até agora não precisamos disso.


Sim, existem alguns padrões (embora algumas liberdades na definição de padrão) que emergiram:

  1. jsonapi.org - A jsonapi.org JSON abrange também a criação e atualização de recursos, não apenas respostas.
  2. JSend - Simples e provavelmente o que você já está fazendo.
  3. Protocolo OData JSON - Muito complicado.
  4. HAL - Como o OData, mas com o objetivo de ser HATEOAS .

Também há formatos de descrição da API JSON:


O JSON-RPC 2.0 define um formato padrão de solicitação e resposta e é uma lufada de ar fresco depois de trabalhar com APIs REST.





response