Providing RESTful endpoints for one to several relationships

Question

Consider the following relationship between two resources

• The college has many faculties.
• Faculty refers to College

Obviously, faculty is not a first class resource here.

Now I need endpoints for the following operations.

• Create a new faculty in this college of this farm. One possible way to do this in two operations.
  • POST /faculties/
  • PUT /college/1/faculties
• Remove faculty from this college. Again two operations
  • GET /college/1/faculties : list of related faculties. Each of them will contain its own URL, for example /faculties/1 .
  • DELETE /college/1/faculties/1 : The URL looks better, but how do I open this URL?
• Add one or more faculties to this college.
  • PUT /college/1/faculties , which accepts the full list of faculties of this college.
• Delete this specific sector as a whole.
  • DELETE /sectors/1 : It looks good, but you need to take care of the cache /faculties/1/sectors .

What would be better in this case? I read about exposing membership resources, but with this approach, if the college has 10 faculties, it will take 10 separate HTTP calls to get all members from membership.

In addition, this is just one small part of a complete relationship tree. To extend this further, let's say the system has

• The faculties have many departments.
• There are many laboratories in the department, etc.

In addition, in a RESTful architecture, a client should never fill in URLs.

Any suggestion?

Answer 1

In the past, I wrote a post on how OData implements such aspects (the function "navigation properties"). See this link: https://templth.wordpress.com/2014/12/08/updating-data-links-of-odata-v4-services-with-olingo/ .

This other link may also give you some interesting tips, because at the end it describes the URLs and the corresponding payloads: http://www.asp.net/web-api/overview/odata-support-in-aspnet-web- api / odata-v4 / entity-relations-in-odata-v4 .

I think there are two cases that you can use to minimize the number of requests: working with a link or providing content. I mean, if the resource detects (based on the content or user header) the sent content so that it knows whether it needs to process the link (only the attachment) or the content (creation and attachment).

I would see the following possible queries for multiple capacities (college → faculties):

• POST /faculties/ : Add a faculty without being tied to college.
• POST /college/1/faculties : attach the faculty to the college and eventually create it if it does not exist (based on the submitted content).
• DELETE /college/1/faculties/?ref=/faculties/1 to separate the faculty from college.

Something you might also consider is to put a link to the college at the faculty ( POST /faculties ). This way you can attach an element during its creation.

Otherwise, the implementation of this PUT /college/1/faculties intended to replace the whole view in such a way that all the abilities that are tied to a particular college.

You can also use the POST or PATCH method to minimize the number of requests. You can see these answers for more details: REST API - Bulk create or update in a single request and How to update the collection of REST resources . This approach allows you to create elements in one call and then attach them. It allows you to collect processing elements.

Hope I was clean and that helps you, Thierry

Answer 2

Using:

• POST: creating new entries.
• PUT: to edit existing records.
• DELETE: delete existing entries.
• GET: to get one or a list of records.

These are standard methods used to save saved data.

And do not mix entity with endpoint addresses. Treat each object at the end points, as if there was no connection between them. And always in the singular, the endpoint ends with faculty , not faculties .

 POST /college/ POST /faculty/ POST /department/ POST /lab/ 

If you need to differentiate the return of a list of records from a single record, always return the list of records with GET and return a single record with GET with the ID parameter. The same method and the same endpoint can be used to extract both (list and single entry). There is no need to create different endpoints to retrieve lists and single entries.