Métodos RESTful API; CABEÇA E OPÇÕES


92

Estou escrevendo um módulo RESTful API para um aplicativo em PHP e estou um pouco confuso com os verbos HEADe OPTIONS.

  • OPTIONS  Usado para recuperar os verbos HTTP disponíveis para um determinado recurso?
  • HEAD Usado para determinar se um determinado recurso está disponível?

Se alguém pudesse esclarecer * esses verbos, agradeceríamos muito.

* O esclarecimento foi com relação às arquiteturas de API RESTful que re-propõem verbos HTTP. Desde então, cheguei à conclusão de que ambos HEADe nãoOPTIONS devem ser reaproveitados e, em vez disso, comportar-se de maneira previsível como qualquer aplicativo HTTP deveria. Ah, como crescemos em 2 anos.


provavelmente porque as especificações HTTP estão prontamente disponíveis na web.
Gordon

@Gordon - Bastante justo, e embora eu entenda que os serviços RESTful API se destinam a tirar proveito das especificações HTTP existentes, acho que presumi algum desvio parcial para detalhes de implementação. Foi mal.
Dan Lugg

14
As especificações de quase tudo estão disponíveis na web. As perguntas sobre o SO são para esclarecimentos além da documentação. Isso se encaixa nisso.
Andrew Ensley,

Respostas:


60

Conforme: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

9.2 OPÇÕES

O método OPTIONS representa um pedido de informação sobre as opções de comunicação disponíveis na cadeia de pedido / resposta identificada pelo Request-URI. Este método permite que o cliente determine as opções e / ou requisitos associados a um recurso, ou as capacidades de um servidor, sem implicar em uma ação de recurso ou iniciar uma recuperação de recurso.

As respostas a esse método não podem ser armazenadas em cache.

Se a solicitação OPTIONS incluir um corpo de entidade (conforme indicado pela presença de Content-Length ou Transfer-Encoding), o tipo de mídia DEVE ser indicado por um campo Content-Type. Embora esta especificação não defina qualquer uso para tal corpo, extensões futuras para HTTP podem usar o corpo OPTIONS para fazer consultas mais detalhadas no servidor. Um servidor que não oferece suporte a essa extensão PODE descartar o corpo da solicitação.

Se o Request-URI for um asterisco ("*"), a solicitação OPTIONS se destina a ser aplicada ao servidor em geral, e não a um recurso específico. Como as opções de comunicação de um servidor geralmente dependem do recurso, a solicitação "*" só é útil como um método do tipo "ping" ou "no-op"; ele não faz nada além de permitir que o cliente teste os recursos do servidor. Por exemplo, isso pode ser usado para testar um proxy para conformidade HTTP / 1.1 (ou falta dela).

Se o Request-URI não for um asterisco, a solicitação OPTIONS se aplica apenas às opções disponíveis ao se comunicar com esse recurso.

Uma resposta 200 DEVE incluir quaisquer campos de cabeçalho que indiquem recursos opcionais implementados pelo servidor e aplicáveis ​​a esse recurso (por exemplo, Permitir), possivelmente incluindo extensões não definidas por esta especificação. O corpo da resposta, se houver, DEVE incluir também informações sobre as opções de comunicação. O formato de tal corpo não é definido por esta especificação, mas pode ser definido por futuras extensões para HTTP. A negociação de conteúdo PODE ser usada para selecionar o formato de resposta apropriado. Se nenhum corpo de resposta for incluído, a resposta DEVE incluir um campo Content-Length com um valor de campo "0".

O campo de cabeçalho de solicitação Max-Forwards PODE ser usado para direcionar um proxy específico na cadeia de solicitação. Quando um proxy recebe uma solicitação OPTIONS em um absoluteURI para o qual o encaminhamento de solicitação é permitido, o proxy DEVE verificar um campo Max-Forwards. Se o valor do campo Max-Forwards for zero ("0"), o proxy NÃO DEVE encaminhar a mensagem; em vez disso, o proxy DEVE responder com suas próprias opções de comunicação. Se o valor do campo Max-Forwards for um número inteiro maior que zero, o proxy DEVE decrementar o valor do campo ao encaminhar a solicitação. Se nenhum campo Max-Forwards estiver presente na solicitação, a solicitação encaminhada NÃO DEVE incluir um campo Max-Forwards.

9.4 CABEÇA

O método HEAD é idêntico ao GET, exceto que o servidor NÃO DEVE retornar um corpo de mensagem na resposta. A metainformação contida nos cabeçalhos HTTP em resposta a uma solicitação HEAD DEVE ser idêntica à informação enviada em resposta a uma solicitação GET. Este método pode ser usado para obter metainformações sobre a entidade implícita na solicitação sem transferir o próprio corpo da entidade. Este método é freqüentemente usado para testar links de hipertexto quanto à validade, acessibilidade e modificações recentes.

A resposta a uma solicitação HEAD PODE ser armazenável em cache no sentido de que a informação contida na resposta PODE ser usada para atualizar uma entidade previamente armazenada em cache a partir desse recurso. Se os novos valores de campo indicam que a entidade em cache difere da entidade atual (como seria indicado por uma alteração no Content-Length, Content-MD5, ETag ou Last-Modified), então o cache DEVE tratar a entrada do cache como obsoleto.


1
Obrigado @sdolgy pela citação abrangente; entretanto, na prática, muitos módulos de API RESTful bem-sucedidos devem aderir a todos esses padrões HTTP ou há uma resposta reduzida aceitável para essas operações? Não por preguiça, mas meramente por curiosidade; Provavelmente implementarei tudo o que é necessário para aderir.
Dan Lugg

2
se você está construindo o seu próprio, o que presumo que esteja, deve tentar manter algum alinhamento com os padrões documentados para tornar sua vida mais fácil ... e a das pessoas que consomem sua API ... não siga a Microsoft. É bom se alinhar com
RFCs

Obrigado @sdolgy. Tendo informado o documento vinculado, percebi no final o CONNECTverbo. Seria uma escolha ruim consumir esse método para autenticação RESTful?
Dan Lugg

Não tenho certeza se era o propósito pretendido "Esta especificação reserva o nome do método CONNECT para uso com um proxy que pode mudar dinamicamente para ser um túnel (por exemplo, túnel SSL [44])." ... pode ser útil postar outra pergunta em um dos sites
stackexchange.com

2
@DanLugg Seu aplicativo pode não estar utilizando CONNECTuma forma de encapsulamento SSL, mas imagine o que aconteceria se um consumidor de seu aplicativo tivesse um proxy implementado CONNECTda forma como foi especificado no RFC, as solicitações podem não ser repassadas ao seu inscrição.
Steve Buzonas

80

OPTIONSmétodo retorna informações sobre API (métodos / tipo de conteúdo)

HEADmétodo retorna informações sobre o recurso (versão / comprimento / tipo)

Resposta do servidor

OPÇÕES

HTTP/1.1 200 OK
Allow: GET,HEAD,POST,OPTIONS,TRACE
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:24:43 GMT
Content-Length: 0

CABEÇA

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:12:29 GMT
ETag: "780602-4f6-4db31b2978ec0"
Last-Modified: Thu, 25 Apr 2013 16:13:23 GMT
Content-Length: 1270
  • OPTIONS Identificar quais métodos HTTP um recurso suporta, por exemplo, podemos EXCLUIR ou atualizá-lo por meio de um PUT?
  • HEADVerificando se um recurso foi alterado. Isso é útil ao manter uma versão em cache de um recurso
  • HEAD Recuperar metadados sobre o recurso, por exemplo, seu tipo de mídia ou seu tamanho, antes de fazer uma recuperação possivelmente cara
  • HEAD, OPTIONSTestando se um recurso existe e está acessível. Por exemplo, validar links enviados por usuários em um aplicativo

Aqui está um artigo bom e conciso sobre como HEAD e OPTIONS se encaixam na arquitetura RESTful.


9
Ótima resposta, uma pena que vai pagar a multa de atraso para a festa. A resposta aceita copiada e colada nem mesmo começa a abordar o lugar desses verbos em uma arquitetura RESTful especificamente.
Todd Menier

1
Seu link está morto. Aqui está seu último instantâneo: web.archive.org/web/20160528151316/https://…
kolobok

29

OPTIONS informa coisas como "Quais métodos são permitidos para este recurso".

HEAD obtém o cabeçalho HTTP que você obteria se fizesse uma solicitação GET, mas sem o corpo. Isso permite que o cliente determine as informações de armazenamento em cache, que tipo de conteúdo seria retornado, que código de status seria retornado. A disponibilidade é apenas uma pequena parte dela.


Obrigado @Quentin; OPTIONSfoi o que imaginei, e tal implementação será fácil com a minha abordagem existente. De acordo com a citação RFC de sdolgy, OPTIONSnão define nenhum padrão no formato. É assumido que o formato da resposta é o mesmo que as outras respostas? ( por exemplo, JSON, XML, etc. )
Dan Lugg

@Tomcat Citando o RFC: "A negociação de conteúdo PODE ser usada para selecionar o formato de resposta apropriado." Em outras palavras: a resposta deve ser o que a Solicitação solicitou no cabeçalho.
Gordon
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.