Another Rest API relations - api

ive been digging through quite a few questions on here about restful relations but havent quite found what im after.
consider this scenario
GET /api/users(?include=custom_fields) - returns an array of users, optionally including relations as nested properties
GET /api/users/1(?include=custom_fields) - returns a single user object
POST /api/users - creates a new user (if the request includes an array of "custom_fields" these are created and linked)
PUT /api/users/1 - replaces user entity with supplied payload
PATCH /api/users/1 - updates the user properties provided
DELETE /api/users/1 - deletes
GET /api/users/1/custom_fields - gets all users custom_fields
PUT /api/users/1/custom_fields - deletes all existing custom_fields and creates ones provided
PATCH /api/users/1/custom_fields - appends if not exists, or creates new custom fields for this user
DELETE /api/users/1/custom_fields - deletes all custom fields for user
DELETE /api/users/1/custom_fields/{id} - deletes custom field for use by id.
this all makes sense to me and is working as expected, however im now implementing a "user edit" screen in my admin area, this shows the user object AND the custom fields.
right now the only RESTFUL way i can see to save this form is to:
PATCH to /api/users/{id}
to save the user. when thats done,
PUT to /api/users/{id}/custom_fields
to update the custom fields.
not ideal but would work, however going forward i know for sure i will have other related resources like user roles, emails, etc.
this doesnt change the situation it just means alot more endpoints.
something about this smells to me. to simply save a user im having to make requests to at least two endpoints.
how would you suggest best to handle this without the two different requests?

The simplest solution would be to just include all those (custom fields, roles, etc.) into the User representation, you already seem to be doing that anyway on GET and POST. Just extend that to PUT and PATCH too.
If you already support some media-type for the PATCH method on Users, then you could conceivably extend that to define adding/removing custom fields, roles, whatever you need.

Related

Designing a REST API

In my application, I will have clients trying to book some slots. For this, the client will give some input and based on that input, I have to first create these slots and then return them to the client. Then after getting the slots, the user will book one of these slots. This "book" action is not creating any new resource but simply modifying 2 existing resources.
How do I design my URIs and what methods should I use?
EDIT:
I have 1 existing resource whose URI is: /api/v1/vehicle/id
Using the application front-end a user will fill some form data, with fields date and booking-type and submit it. Then this data will be used by the backend to "calculate" (no resource called slots exists currently) booking slots available to the user. These calculated slots will then be saved in the DB and returned as a response to the user. Out of these slots, the user will book a slot. However, this book action will not create any new resource, instead it will simply modify an existing vehicle resource (add booking related data to it) and the slots object returned by the previous request. I want to create a REST API for this.
I was thinking of doing it like this:
POST /api/v1/slot (1)
PUT/PATCH /api/v1/vehicle/id (2)
PUT/PATCH /api/v1/slot/id (3)
First, I am not sure if I should use PUT or PATCH here, in both (2) and (3). I will only be supplying partial updates to the request. Second, when the user selects a slot and clicks on book button, the front end can only send 1 request to the server. But here, I need to modify 2 resources. How do I do this? I guess I should create 1 URI like /api/v1/createbooking and use the POST method. Then in my backend call 2 different methods to update vehicle and slot objects. Is this URI structure and naming good?
How do I design my URIs and what methods should I use?
How would you do it with web pages?
It sounds like you would have the user navigate to a form which collects the date, booking type, etc. The user submits the form, and the information is sent to the server; because this is not an essentially read-only operation, we'd expect the form to indicate that the POST method should be used.
The server would make its local changes, and present to the user a new form, with the input controls presenting the available options. Once again, choosing a slot doesn't seem to have read-only semantics (we're passing information to the server), so we would see POST again.
What are the URI targets? One way to choose which resources should handle the POST requests is to consider the implications of cache invalidation; because caches know to invalidate the target-uri of a successful POST request, it can be useful to target a resource that is likely to change when the request is successful.
My guess would be that first post would go to the resource that presents the slot choices (since what we are doing is generating new choices for the customer).
For the second submission, since the representation of the vehicle is what is going to be changed by selecting a slot, it makes sense to send that POST request to the vehicle uri.
In general, think about how you read (GET) the changing information from the server; you change that information by sending some request to the same URI.
I am not sure if I should use PUT or PATCH here
PUT and PATCH are typically available together, not as distinct things. They are two different methods for sending a replacement representation of a resource.
A simple example: if you wanted to change the title of /home.html, you could either PUT the entire HTML document with the new title, or you could PATCH the HTML document by sending a patch-document in some format that the server understands.
In other words, both of these methods have remote authoring semantics; we normally would choose between them based on considerations unrelated to your domain model (if the document is small relative to the size of the HTTP headers, a client would usually choose PUT for the additional idempotent semantic guarantees. If the document is really big, but the change is small, we might prefer PATCH).
I need to modify 2 resources.
There's no rule that says a request may only modify one resource. The side effects of the changes may impact the representations of several resources (see 4.3.3 and 4.3.4 of RFC 7231).
What's tricky is telling general purpose clients (and intermediate components) which cached representations are invalidated by the change. Out of the box, we only have semantics for the effective request uri, the Location and the Content-Location. Location and Content-Location already mean something, so you can't just hijack them without the potential of introducing a big mess).
You could do it with Linked Cache Invalidation, using "well known" link relations to identify other documents that have been changed by the request. Unfortunately, LCI doesn't seem to have achieved the status of a "standard", so we may be out of luck for the time being.

If a 'many-to-many' field is added to directus_users

Firstly, I love the Directus CMS and I chose to implement it on my new project. So far I am just loving it.
Now I have this issue where the user create functionality was added, with email verification etc all was good. Until I added a new o2m field in the directus_fields & proper relations were made. Works well in the admin panel, but while I want any user to signup from frontend the api now throws error code 3, 401 Unauthorized request. I tried all the permissions, for the junction collection, the field one collection and also the directus_users collection.
PS: It works back normal when I tried deleting the field from the directus_fields table. Thats why I am actually guessing that the issue is from the relations related permissions. And the relation works well and fine from the admin panel.
So again my question is, if an o2m 'many-to-many' field is added to 'directus_users' collection what are the permissions, alterations required for public user/create functionality. The field is not marked as required.
I am using version 8.8.1
For now, I made a temporary solution.
Removed the o2m field from the directus_users table, instead created a new collection containing the additional users_data and created the many-to-many field in it so the registration is secure and also doesn't require to tamper the directus_users table. All I had to do in addition was to modify the extra request parameters from the frontend.
Although, I still believe my question is a valid one.

Need help understanding REST API endpoints

I don't quite grok how to sensibly structure a REST (or REST-like) API.
Imagine an API for creating and sending out newsletter emails. You might have the following nouns/resources: newsletters (subject, body, etc.), mailing lists (collections of recipients), and recipients (email addresses and associated data).
So you could use PUT to create a resource and be returned its ID:
/newsletter
/list
/user
You could obtain information on a resource using GET:
/newsletter/[id]
/list/[id]
/user/[id]
You can update an existing resource using PATCH (or should this be POST?):
/newsletter/[id]
/list/[id]
/user/[id]
You can delete a resource using DELETE:
/newsletter/[id]
/list/[id]
/user/[id]
Is the above correct?
What endpoints are sensible for actions like sending a newsletter to a list, adding a user to a list?
Does the following make sense, and is it RESTfull?
/newsletter/[newsletter_id]/send/[mailinglist_id]
/list/[list_id]/add/[user_id]
/list/[list_id]/remove/[user_id]
Is it redundant or unhelpful to have list/[id]/add/[id] and list/[id]/remove/[id] endpoints for lists, when users could be added or removed via PATCH at /list/[id] ?
What about searching for a users' ID via a property like email address or name? Or getting a list via an identifier like its name or when it was created?
You pretty much nailed it, except with the /list/[list_id]/add/[user_id] and /list/[list_id]/remove[user_id], because you have verbs in the URL - that is the purpose of the HTTP methods. Change them to, for example:
PUT (or POST) to /list/[list_id]/users/ for adding a user to the list
and
DELETE to /list/[list_id]/users/[user_id]
For search, I'd go with parameterized url for the list of resources, like:
/newsletter/?name=dfjkhskdfh
These verbs are often confused:
To create an entity you use POST
To update - PUT
These things could be treated in the following way:
POST /newsletters/[newsletter_id]/mailinglists/[mailinglist_id]/mailingfacts - performs sending the letters, it's like adding a fact of mailing to the collection
/lists/[list_id]/[user_id] - adds a user to the list
/lists/[list_id]/[user_id] - deletes the user from the list.
Is it redundant or unhelpful to have list/[id]/add/[id] and list/[id]/remove/[id] endpoints for lists, when users could be added or removed via PATCH at /list/[id] ?
It is bad/unhelpful. One of the ideas of REST is that the end points are resources and not a Remote Procedure Call (RPC). add or remove is suggesting a procedure to call.
Further GET requests should be side-effect free, that is, they don't do any updates. Further Roy Fielding explains GET as:
retrieval of information that should be a representation of some resource
So GET is only for retrieval, not for sending data (i.e. which user to add/remove).
The other very dangerous problem with list/[id]/remove/[id] is that if a spider or your test framework is going around your site it could start deleting items.

When should an object be included as a member of another object, and when should it always standalone?

An example problem:
On Stack Overflow, a question page shows a number of different answers. In displaying these answers, the site also gives information about the author of the answer. This means that although the number of badges a given user has has nothing to do with an answer in and of itself, that data still needs to be retrieved in order to display the page.
From what I can see, there are three different ways to go about pulling this view data in a model:
A Post object could include a full User object as a member. The view would then access the user like this: $post->user->getReputation(). This seems cleaner, since a Controller could just request the posts and be done with it, but yet inefficient since a Post probably doesn't always need a full-blown User. I suppose it works well enough if the User object is relatively light, which it probably would be. The problem would then be that you would need to duplicate User retrieval code as part of the Post retrieval query.
The Post object could hold just an ID for a User. When the Post, or Posts, are returned to the Controller, the Controller could then extract the unique User IDs from the returned set and pass them to a User factory. The returned User objects would then be passed along with the original Posts set to the View as a separate collection. The view could then grab user info using something like $users[$post->getUserId()]->getReputation().
A hybrid approach: Include the User object inside the Post object, but have the unique id extraction and User retrieval as part of the Post retrieval method. i.e. Post::getPosts() would grab all relevant posts and convert them to objects with null User members, then it'd extract all user ids and pass them to User::getUsers(), then assign the Users to the relevant Posts before returning the set of Posts to the caller.
I guess what I'm getting at is, how do I know when an object needs to contain another object fundamentally? Is it unclean/a code smell to instead have such related objects returned separately, with neither object knowing the other has been retrieved. I'm leaning towards the separate retrieval concept - it seems the most efficient - but it really does feel like they're too related for that to make sense.
There is also a solution in between 1 and 2. You can have a lazy loading proxy for the user class. With this solution you can have best of both worlds because the proxy is interchangeable with the real thing so depending on the situation you can have the object itself or the proxy.
Edit:
I'll try to explain this with an example.
Say that you have a view where you don't need user info, then you can instruct/configure your post factory to use the lazy proxy (see wikipedia)for the user which will only contain an ID. So no access to users is needed.
In another view you occasionally need to access user info but only for some posts, here again you instruct/configure your factory to include the lazy proxy for the user.
But when you actually need access to the user info, you can access the proxy object that will then load the actual user object and redirect messages to it.
In yet another view you need both post and user info, so here you instruct your post factory to use actual user objects.
It seems to me that this is another case of dependency injection. A general enough idea that could help you.
DEPENDENCY INJECTION WIKI
Read something about the Inversion Of Control also.
why not add optional member to model to know informations?? you can ignore when you don't need and can use when you do need.

Jira SOAP API custom field

Hi I'm am trying to get the list of issues from a JIRA server using the SOAP API provided by JIRA.
I'm trying to filter the issues based on a custom field (and latter I will want to set that custom field).
If I get the list of issue it returns the custom fields for those issues along with them (I get customfieldId, key, values for each custom field) and I can get the custom field with getCustomFields methods provided by the API (to look for the ID of the field with a given name).
The issue I have is that if I login with an account that is not an admin (using the API) I can't call the getCustomFields method (it throws an exception saying I have to be an admin to do that).
My question is: Is there any other way to know which is the ID of the custom field I desire that can be done using a normal user account?
Also if you know how to set a custom field for an issue, it would also be very helpful :) (I would also like to be able to do it with a regular user account).
You have to be an admin to get a list of custom fields. Any 'normal' account can act on the custom fields via the API provided the user knows the customfield ID.
You can set the value of a custom field too, even with a 'normal' account. Again, the user needs the appropriate permissions to do this. Example provided here.
More here and here.
You can also use getFieldsForEdit(token, issueKey), which will return RemoteField[] for all fields available for edit on that issue (even if it has not yet been defined on the issue). It does not require admin permissions, but because it has the word "Edit" in the method, it does require that you have permission to edit the issue (which means, e.g., if the issue is status=Closed, it will raise an exception unless you allow editing closed issues. Unfortunately, I have yet to find a way to retrieve the RemoteField[] list (in order to map id to name), so getCustomFields() and getFieldsForEdit() appear to be the only options.
Have you tried getting a list of issues from the project, picking one, zeroing out the data, and using that as a template? That might work.
SOAP is being deprecated in favor of the REST API, which also has a better method to get this information