Como implementar corretamente a API REST de armazenamento key = value

5

Sou novo na API REST, então decidi me familiarizar com isso criando uma pequena API de serviço da web. Eu tenho seu design escrito e gostaria que você o revisasse. Eu sinto que cometi alguns erros ao projetar e entender os conceitos do REST, que eu tento abordar com perguntas sobre o meu design no final. Não tenho muita certeza sobre o uso de URLs para a API.

O serviço da Web que eu tento criar fornece uma maneira para um usuário armazenar pares chave = valor, ou seja, recuperar o valor sabendo sua chave, atualizar o valor de uma chave existente e excluir uma chave existente. Todo o conjunto de ações do CRUD!

Aqui está o que eu criei.

Controle de versão

Como minha API pode evoluir, quero ter uma noção das versões da API, por isso tenho

GET api.example.com/supported-versions

Que retorna uma lista JSON de inteiros denotando as versões da API suportadas.

A API estará disponível em api.example.com/{VERSION}/ endpoint, por exemplo api.example.com/1/ para a primeira versão.

Key = armazenamento de valor

GET api.exmaple.com/1/keys/{KEY}

Permite que um usuário obtenha um valor associado a uma chave KEY . O servidor responde com um código de status (200, 404, etc.) e um valor de texto em sucesso, ambos codificados em JSON.

POST and PUT api.exmaple.com/1/keys/{KEY}?value={VALUE}

Permite que um usuário crie / atualize o valor associado à chave KEY . O servidor retorna um código de status (200, 404, etc.). VALUE é uma string de texto.

DELETE api.exmaple.com/1/keys/{KEY}

Permite que um usuário exclua um par key = value com a chave KEY . O servidor que irá apagar o par chave = valor e retornar um código de status (200, 404, etc).

Vamos imaginar que haja uma configuração de autenticação OAuth2, que é usada para os métodos POST / PUT / DELETE acima (mas não é possível GET que alguém pode GET, você não precisa de autenticação para isso), então há uma maneira para identificar exclusivamente um usuário e acompanhar quais pares key = value pertencem a qual usuário.

Agora, quero que um usuário autenticado consiga obter uma lista de todas as chaves que possui, para que eles não precisem armazenar essas informações no lado do cliente para enviar solicitações DELETE ou PUT mais tarde.

GET api.exmaple.com/1/keys?page={PAGE}

Isso permite que um usuário obtenha uma lista de todas as chaves existentes que criou. PAGE é um parâmetro opcional. O usuário pode aumentar a contagem de páginas até que o usuário receba um código de status de erro. Ele retorna uma lista paginada de todas as chaves existentes que um usuário criou e também um código de status (200, 404, etc.).

Há algo de errado com essa API?

A primeira seção GET / POST / PUT / DELETE da Key = value storage deve estar em /keys/ ou /values/ ?

Tudo bem que o último "GET", aquele que retorna todas as chaves que um usuário possui, também seja /keys/ ?

    
por Waffle Lord 03.01.2016 / 05:03
fonte

2 respostas

6

A sua solução está bem, poupe algumas coisas:

  1. As APIs REST de versão no nível do recurso geralmente não são uma boa prática, embora isso não seja necessariamente uma exibição de consenso. Consulte aqui para alguns comentários e links para mais discussões.

  2. Para sua segunda pergunta, você provavelmente poderia argumentar se /keys/{id}/ ou /values/{id}/ está correto, mas meu instinto seria usar keys , já que é o "pai" da tupla ou usaria um nome totalmente diferente, como /data/ ou /elements/ , ou seja lá o que essas coisas representem.

  3. Eu provavelmente teria diferentes métodos GET para todo o dicionário de valor-chave, por exemplo /keys/{id} / e um recurso separado para aqueles para um usuário específico, por exemplo /users/{id}/keys/{keyId} .

Finalmente, não é ótimo (embora possível) usar strings de consulta com os métodos POST / PUT / DELETE. É uma string consulta , afinal. Em vez disso, você pode usar o POST /data/ e colocar o par de valores-chave como dados JSON no corpo da solicitação. Veja esta questão também.

    
por 03.01.2016 / 05:37
fonte
1

Quando o serviço REST retorna uma lista de recursos, como as chaves do usuário ou as versões disponíveis, as estruturas de retorno (json) contêm URLs para esses recursos. Google para "dados vinculados" para ver os benefícios dessa abordagem.

Por exemplo o pedido:

HTTP> GET /Data/Version=1/User=Kasper/My_keys

resultaria na resposta:

200

{ keys: 
   [ 
      { name: "SO_account",
        link: "http://api.example.com/Data/Version=1/keys/SO_Account
      },
      { name: "Facebook_account";
        link: "http://api.example.com/Data/Version=1/keys/Facebook_account"
      }
   ]
}
    
por 06.01.2016 / 15:27
fonte