Best Practices for URI in RESTful APIs

9

I am doubtful about the URIs of some api resources that I am developing. I have the projects and activities resources with respect to 1-N , ie a project has multiple activities and an activity belongs to a project.

What is the right way or the best way to deal with REST conventions? I would like some examples for requests GET , POST , PUT and DELETE for these resources.

EDIT: I have rephrased the question.

    
asked by anonymous 21.10.2016 / 13:28

2 answers

6

If the project has activities, this is the correct way to represent, differentiating the PUT from PATCH . Since I understand that there will be the /projetos/ feature and only /atividades/ for GET, I will organize the possible endpoints by HTTP methods.

GET

  • Search all projects: GET /projetos/
  • Search for project number 1: GET /projetos/1
  • Search all project activities 1: GET /projetos/1/atividades
  • Search activity 1 of project 1: GET /projetos/1/atividades/1 , but an option is also to create a /atividades/1 .
  • Search activity 1: GET /atividades/1
  • Search all activities: GET /atividades/

POST

  • Create project number 1: POST /projetos/ , passing in the request body the project information
  • Create an activity in project number 1: POST /projetos/1/atividades , passing in the body of the request the activity information

You could also have a POST /atividades/1 , by passing the project number in the body. This decision will depend on how you want to represent the available resources. This "break" can be done when your endpoint gets too long or you think it will get better organized. If you choose to break, the ideal is to maintain consistency and also make the same break in other HTTP methods of the resource.

PUT

Used to replace an existing entire resource with another.

  • Replace everything with the content of project number 1: PUT /projetos/1 , passing in the body of the request all new project information
  • Replace all an activity of number 1 in project number 1: PUT /projetos/1/atividades/1 , passing in the body of the request the new activity information

PATCH

Used to change only one or some resource-specific information.

  • Update any project information from number 1: PATCH /projetos/1 , passing in the body of the request only the project information you would like to update
  • Update any information from a number 1 activity in project number 1: PATCH /projetos/1/atividades/1 , passing in the body of the request only the activity information

DELETE

  • Remove project number 1: DELETE /projetos/1
  • Remove a number 1 activity in project number 1: DELETE /projetos/1/atividades/1 .

The DELETE can also be used when the sense is a logical exclusion of the resource, because sometimes the staff only associates this method with DELETE of the database, which makes no sense.

Also remember return consistent HTTP codes . Example: 201 for creating a resource via POST , 200 or 204 on PUT and DELETE , 404 for when not finding resource, etc.

    
26.10.2016 / 03:46
4

You could use the following approach:

get /projetos # Lista de projetos    
post /projetos # Criar um projeto

get /projetos/1 # Buscar o projeto com id 1
put /projetos/1 # Atualizar o projeto com id 1
delete /projetos/1 # Deletar o projeto com id 1

get /atividades # Todas as atividades
post /atividades # Criar nova atividade

get /atividades/1 # Atividade com id 1
put /atividades/1 # Atualizar atividade com id 1
delete /atividades/1 # Deletar atividade com id 1

get /projetos/1/atividades # Lista de atividades do projeto com id 1

Remembering RFC 5789, the put method would be to replace a resource. Use the patch to modify it. link

You can check out these questions about URI design

link

link

    
23.10.2016 / 16:43