Guia JSON do Google

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

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

E se o seu cliente é JS, pode usar if ("error" in response) {} para verificar se há erro.

Acho que um padrão de defacto não surgiu realmente (e talvez nunca). Mas, seja como for, Aqui está a minha opinião:

Pedido bem sucedido:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Pedido mal-sucedido:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

Vantagem: os mesmos elementos de topo nos casos de sucesso e de erro

Desvantagem: sem código de erro, mas se você quiser, você pode alterar o estado para ser um código (sucesso ou falha),- ou - você pode adicionar outro item de nível superior chamado "código".

Assumindo que a sua pergunta é sobre o design de webservices REST e mais precisamente sobre o sucesso/erro.

1. Utilize apenas o código de estado HTTP para indicar se houve um erro e tentar limitar-se aos padrões (normalmente deve ser suficiente).

   É um padrão independente da sua api.
= = ligações externas = =

2. Utilizar HTTP Status + JSON body (mesmo que seja um erro). Definir uma estrutura uniforme para erros (ex: código, mensagem, razão, tipo, etc) e usá-lo para erros, se for um sucesso, então apenas retornar a resposta json esperada.

   • prós: continua a ser o padrão à medida que usa os códigos de estado HTTP existentes e devolve um json a descrever o erro (fornece mais informações sobre o que aconteceu).
   • Cons: o JSON de saída irá variar dependendo se for um erro ou sucesso.

3. Esqueça o http status (ex: sempre de status 200), sempre usar o json e adicionar na raiz da resposta de um booleano responseValid e um objeto de erro (código,mensagem,etc) que será preenchido se for um erro, caso contrário os outros campos (sucesso) são preenchidos.

   • Prós: o cliente lida apenas com o corpo da resposta que é uma string json e ignora o status(?).

   • Cons: menos padrao.

Cabe-te a ti escolher:)

Dependendo da API eu escolheria 2 ou 3 (eu prefiro 2 para a API json rest). Outra coisa que eu experimentei em projetar a API de descanso é a importância da documentação para cada recurso (url): os parâmetros, o corpo, a resposta, os cabeçalhos etc + exemplos.

Também te recomendo que uses jersey (implementação jax-rs) + genson (biblioteca de dados java/json). Você só tem que cair genson + jersey no seu classpath e json é automaticamente suportado.

Editar:

• A Solução 2 é a mais difícil de implementar, mas a vantagem é que você pode lidar bem com exceções e não só erros de negócios, o esforço inicial é mais importante, mas você ganha a longo prazo.

• A Solução 3 é a mais fácil de implementar tanto no lado do servidor e no cliente, mas não é tão agradável como você terá que encapsular os objetos que você quer retornar em uma resposta objecto que contém também o erro responseValid+.

Não serei tão arrogante ao afirmar que este é um padrão, por isso vou usar o formulário "eu prefiro".

Eu prefiro resposta terse (ao solicitar uma lista de /artigos quero uma lista de artigos JSON).

Nos meus desenhos eu uso HTTP para o relatório de Estado, um 200 devolve apenas a carga.

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

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

Volta 404 se o modelo/controlador/URI não existir

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

Fundamentação:

O JSON é suposto ser um formato de carga útil , não é um protocolo de sessão. Toda a idéia de sessões verbosas-ish payloads vem do mundo XML / SOAP e várias escolhas equivocadas que criaram esses projetos inchados. Depois de percebermos que era uma enorme dor de cabeça., o objetivo do REST / JSON era beijá-lo, e aderir a HTTP. Eu não acho que haja nada remotamente [[36]}padrão em qualquer um dos JSend e especialmente não com o mais verboso entre eles. XHR irá reagir à resposta HTTP, se você usar jQuery para o seu AJAX (como a maioria) você pode usar try/catch e done()/fail() chamadas para capturar erros. Não vejo como encapsular relatórios de Estado na JSON é mais útil do que isso.

A seguir está o formato json que o instagram está a usar

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

No entanto, se houver um erro (algo na família 400) eu devolvo um objeto de erro JSON bem formado. Por exemplo, se o cliente está postando um usuário com um endereço de E-mail e número de telefone e um deles é malformado (ou seja, eu não posso inseri-lo na minha base de dados subjacente) eu vou retornar algo como isso:

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

Bits importantes aqui são que a propriedade "campo" deve corresponder ao campo JSON exactamente que não pôde ser validado. Isso permite que os clientes saibam exatamente o que correu mal com seu pedido. Além disso," mensagem " está no local do pedido. Se tanto o "emailAddress" e "phoneNumber" fossem inválidos, então o array "errors" conteria entradas para ambos. Um corpo de resposta JSON 409 (conflito) pode parecer assim:

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

Com o código de estado HTTP e este JSON o cliente tem tudo o que precisa para responder a erros de uma forma determinística e não cria um novo padrão de erro que tenta completar os códigos de estado HTTP. Note, estes só acontecem para o intervalo de 400 erros. Por qualquer coisa na faixa dos 200, Posso devolver o que for apropriado. Para mim é muitas vezes um JSON parecido com HAL. protesto, mas isso não importa aqui.

A única coisa que pensei em Adicionar era um código de erro numérico, quer nos itens da matriz de" erros " ou na raiz do objeto JSON em si. Mas até agora não precisamos.

O RFC 7807: detalhes do problema para o HTTP APIs é no momento a coisa mais próxima que temos de um padrão oficial.

Qual é o tipo do rootnode depende de si, o que ele contém depende de si, se você envia metadados juntamente com a resposta depende de si, se você configura o tipo mime para application/json ou se o deixa como text/plain depende de si (desde que saiba como lidar com a aresta vez).

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

Seguir é o meu assuma o formato de resposta inspirado no Google, Twitter, Amazon e alguns posts na internet:

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

Ficheiro Swagger:

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

JSON-RPC 2.0 define um formato padrão de pedido e resposta, e é uma lufada de ar fresco após trabalhar com APIs de descanso.

A melhor resposta para as apis web que podem facilmente compreender pelos programadores móveis.

Isto é para a resposta de "sucesso"

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Isto é para a resposta de "Erro"

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}