Como criar RESTO URLs sem verbos?

StackOverflow https://stackoverflow.com/questions/1619152

  •  06-07-2019
  •  | 
  •  

Pergunta

Eu estou lutando para determinar como criar URLs repousante. Eu sou tudo para a abordagem tranquila de usar URLs com substantivos e verbos não não entendo como fazer isso.

Estamos criando um serviço para implementar uma calculadora financeira. A calculadora tem um monte de parâmetros que vamos fazer o upload através de um arquivo CSV. Os casos de uso envolveria:

  1. Publique novos parâmetros
  2. pegar as últimas parâmetros
  3. Obter parâmetros de uma determinada data negócios para
  4. Faça um conjunto de parâmetros ativo
  5. Validar um conjunto de parâmetros

Eu recolho a abordagem repousante seria ter as URLs seguinte tipo: 

/parameters
/parameters/12-23-2009

Você poderia alcançar os três primeiros casos de uso com:

  1. POST onde você incluir o arquivo de parâmetro na solicitação post
  2. GET de primeira URL
  3. GET de segunda URL

Mas como você faz a 4ª e 5ª caso de uso sem um verbo? você não precisa de URLs como: 

/parameters/ID/activate
/parameters/ID/validate

??

Foi útil?

Solução

Talvez algo como: 

PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }

Outras dicas

Princípios gerais para um bom design URI:

  • NÃO parâmetros de consulta uso para o estado alter
  • NÃO usar caminhos caso misto se você pode ajudá-la; minúsculas é melhor
  • NÃO extensões específicas implementação usar em seus URIs (.php, py, .pl, etc.)
  • NÃO queda em RPC com seus URIs
  • Do limitar o seu espaço URI, tanto quanto possível
  • segmentos do keep caminho curtos
  • Do preferem quer /resource ou /resource/; criar 301 redirecionamentos da que você não use
  • Do parâmetros de consulta uso de sub-seleção de um recurso; ou seja, a paginação, consultas de pesquisa
  • Do move coisas fora do URI que deve ser em um cabeçalho HTTP ou um corpo

. (Nota: eu não disse "projeto RESTful URI"; URIs são essencialmente opaca em REST) ??

Princípios gerais para HTTP escolha do método:

  • NÃO sempre usar GET para estado alter; esta é uma ótima maneira de ter a ruína Googlebot seu dia
  • NÃO uso PUT a menos que você está atualizando um recurso inteira
  • NÃO uso PUT a menos que você também pode legitimamente fazer um GET na mesma URI
  • NÃO usar POST para recuperar informações que são de longa vida ou que possa ser razoável para o cache
  • NÃO executar uma operação que não é idempotent com PUT
  • Do uso GET para, tanto quanto possível
  • Do usar POST em detrimento de PUT quando em dúvida
  • Do uso POST sempre que você tem que fazer algo que se sente RPC-like
  • Do uso PUT para as classes de recursos que são maiores ou hierárquica
  • Do uso APAGAR em detrimento de POST para remover recursos
  • Do uso GET para coisas como cálculos, a menos que a sua entrada é grande, em que o uso caso POST

Princípios gerais de design de serviços web com HTTP:

  • NÃO metadados colocar no corpo de uma resposta que deve estar em um cabeçalho
  • NÃO colocar metadados em um recurso separado, a menos incluindo criaria uma sobrecarga significativa
  • Do usar o código de status adequado
    • 201 Created após a criação de um recurso; recurso deve existem no momento a resposta é enviada
    • 202 Accepted após a realização de uma operação com sucesso ou a criação de um recurso de forma assíncrona
    • 400 Bad Request quando alguém faz uma operação em dados que é claramente falso; para a sua aplicação este poderia ser um erro de validação; geralmente reservam 500 para exceções.Ele
    • 401 Unauthorized quando alguém acessa seu API quer sem fornecer um cabeçalho Authorization necessário ou quando as credenciais dentro do Authorization são inválidas; não utilize este código de resposta, se você não está esperando credenciais através de um cabeceamento Authorization.
    • 403 Forbidden quando alguém acessa seu API de uma forma que pode ser malicioso ou se eles não estão autorizados
    • 405 Method Not Allowed quando alguém usa POST quando eles deveriam ter colocado usado, etc
    • 413 Request Entity Too Large quando alguém tenta enviar um arquivo inaceitavelmente grande
    • 418 I'm a teapot href="http://tools.ietf.org/html/rfc2324#section-2.3.2" rel="noreferrer"> ao tentar preparar café com um bule de chá
  • do cabeçalhos usar o cache sempre que puder
    • cabeçalhos ETag são bons quando você pode facilmente reduzir um recurso a um valor de hash
    • Last-Modified deve indicar a você que manter em torno de um timestamp de quando os recursos são atualizados é uma boa idéia
      • deve ser dada
    • Cache-Control e Expires valores sensíveis
  • Do tudo o que puder para honrar cache cabeçalhos em um pedido (If-None-Modified, If-Modified-Since)
  • Do redirecionamentos uso quando eles fazem sentido, mas estes devem ser raro para um serviço web

No que diz respeito à sua pergunta específica, POST deve ser usado para # 4 e # 5. Estas operações se enquadram na "RPC-like" diretriz acima. Para # 5, lembre-se que POST não tem necessariamente de uso Content-Type: application/x-www-form-urlencoded. Isso poderia muito bem ser uma carga JSON ou CSV.

Sempre que parece que você precisa de um novo verbo, pensar em transformar esse verbo num substantivo vez. Por exemplo, vire 'Activar' em 'ativação' e 'validar' em 'validação'.

Mas só a partir do que você escreveu Eu diria que a sua aplicação tem problemas muito maiores.

Toda vez que um recurso chamado 'parâmetro' é proposto, deve enviar até bandeiras vermelhas na mente de cada membro da equipe do projeto. 'Parâmetro' pode literalmente se aplicam a qualquer recurso; não é suficiente específica.

O que faz exatamente um 'parâmetro' representa? Provavelmente uma série de coisas diferentes, cada um dos quais deve ter um recurso separado dedicado a ele.

Outra maneira de chegar a este? - quando você discutir sua aplicação com os usuários finais (aqueles que presumivelmente sabem pouco sobre programação) quais são as palavras que eles mesmos usam repetidamente

Essas são as palavras que você deve projetar sua aplicação ao redor.

Se você ainda não tiveram essa conversão com potenciais utilizadores - Paragem tudo agora e não escrever outra linha de código até que você faça! Só então é que sua equipe tem uma idéia do que precisa ser construído.

Eu não sei nada sobre o software financeiro, mas se eu tivesse que adivinhar, diria que alguns dos recursos pode ir por nomes como "Relatório", "Pagamento", "Transfer", e "Moeda".

Há uma série de bons livros sobre esta parte do processo de design de software. Dois posso recomendar são Domain Driven projeto e Análise de Padrões .

O design de seus urls não tem nada a ver com se sua aplicação é RESTful ou não. a frase "RESTful URLS" é, portanto, um absurdo.

Eu acho que você deve fazer mais algumas leituras sobre o RESTO realmente é. RESTO trata os URLs como opaco, e, como tal, não sabe o que está neles, se theres verbos ou substantivos ou qualquer outra coisa. Você ainda pode querer projetar seus URLs, mas que é sobre UI, não descansar.

Dito isso, vamos à sua pergunta: Os dois últimos casos não são RESTful, e não se encaixam em qualquer tipo de esquema repousante. Aqueles são o que você poderia chamar RPC. Se você é sério sobre resto você vai ter que repensar a forma como o aplicativo funciona a partir do zero. Ou isso, ou abandonar REST e apenas fazer seu aplicativo como um aplicativo RPC.

Hrmmm talvez não.

A idéia aqui é que você tem que tudo o deleite como um recurso, então quando um conjunto de parâmetros tem um URL que você possa consultá-la a partir, basta adicionar

get [parametersurl] / validationresults

mensagem [paramatersurl]

corpo: {comando: "Ativar"}

mas, novamente, aquela coisa ativar é RPC, não descansar.

Os requisitos ativar e validar o são situações em que você está tentando mudar o estado de um recurso. Não é diferente que fazer um pedido "concluído", ou algum outro pedido "submetido". Existem inúmeras maneiras de modelar esses tipos de mudança de estado, mas um que eu acho que muitas vezes funciona é criar recursos de coleta de recursos do mesmo estado e, em seguida, para mover o recurso entre as coleções para afetar o estado.

por exemplo. Crie alguns recursos, tais como, 

/ActiveParameters
/ValidatedParameters

Se você quiser fazer um conjunto de parâmetros ativos, em seguida, adicionar esse conjunto com a coleta ActiveParameters. Você poderia passar o conjunto de parâmetros como um corpo de entidade, ou você pode passar um url como um parâmetro de consulta, como a seguir: 

POST /ActiveParameters?parameter=/Parameters/{Id}

A mesma coisa pode ser feita com as ValidatedParameters /. Se os parâmetros não são válidos, em seguida, o servidor pode retornar "Bad Request" para o pedido para adicionar os parâmetros a coleção de parâmetros validados.

Gostaria de sugerir o seguinte recurso e métodos de Meta.

Faça parâmetros activa e / ou validá-los: 

> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<

Verifique se os parâmetros estão ativos e válidos: 

> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
<     'active': true,
<     'require-valid': true,
<     'valid': {'status': false, 'reason': '...'}
< }
<

Em um ambiente de descanso cada URL é um recurso único. Quais são os seus recursos? A calculadora financeira realmente não tem quaisquer recursos óbvios. Você precisa cavar o que você está chamando parâmetros e retirar os recursos. Por exemplo, um calendário de amortização de um empréstimo pode ser um recurso. O URL para o calendário podem incluir start_date, duração (em meses ou yers), período (quando o interesse é agravado), taxa de juros e princípio inicial. Com todos esses valores que você tem um calendário específico de pagamentos: 

http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000

Agora, eu não sei o que você está calculando, mas o seu conceito de uma lista de parâmetros não soa RESTful. Como alguém disse, seus requisitos acima mais som XMLRPC. Se você está tentando para o descanso que você precisa substantivos. Os cálculos não são substantivos, eles são verbo que agir sobre substantivos. Você precisa dar a volta a puxar os substantivos fora de seus calcs.

Editar: solicitações GET Na verdade, a URI teria impedido de permanecer idempotent.

Para a validação no entanto, o uso de HTTP códigos de status para notificar a validade de um pedido (para criar um novo ou modificar um 'parâmetro' existente) caberia um modelo repousante.

Relatório de volta com um código de status 400 Bad Request se os dados apresentados é / são inválidas eo pedido deve ser alterado antes de ser reenviado ( HTTP / 1.1 Códigos de status ).

Esta depende de validação em tempo de submissão, porém, ao invés de adiá-la como no seu caso de uso. As outras respostas têm soluções adequadas para esse cenário.

Licenciado em: CC-BY-SA com atribuição
Não afiliado a StackOverflow
scroll top