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.
Related
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.
I'm struggling to find an answer to this (perhaps because I'm not asking the question properly) ...
I'm building API to expose resources for a basic social networking service I'm creating.
My understanding is that the structure of URLs in an API is essentially a hierarchy, directory like structure. I think that means I can have multiple endpoints to reach the same resources or collections of resource links.
For example:
I have an endpoint
www.domain.api.org/users/{:uid}/posts
Which will return all posts sent by the user or that the user is tagged in. Seems ok, but what if I have an endpoint such as:
www.domain.api.org/posts
Which when hit with a http GET will return all public posts (i.e. all users' posts plus his friends' and public posts).
The difference is that the first URL points to user owned resources whereas the second to public ones (of which the users posts are included of course)
Are these okay or am I doing it the wrong / less sensible way?
To reiterate, can I have multiple endpoints which point to different contexts/views of the same resource?
Basically multiple endpoints for the same resources should be avoided. However in this particular case it does make sense.
What you can do is to introduce optional query param userId to the following endpoint:
www.domain.api.org/posts/?userId=<userId>
If this substitutes the first endpoint you mentioned that's the way to go.
I would like to add ontop of #Opal's answer.
Are these okay or am I doing it the wrong / less sensible way?
Ideally, like Opal mentioned, you would use queryParams in your url. For many applications I have build, I don't know the uids returned from the api beforehand, so selecting an item and passing it inside my url as a query parameter makes sense. But it also has the added benefit of having your key inside your url, allowing you to bookmark it, pass the url to another user and they will automatically see the same data you want them to see.
To iterate: Is your current implementation wrong? No, but ideally you would use a combination of both route parameters are query parameters to achieve this
To create an endpoints, you have to be sure that you have these information at once:
Name of the endpoint
Status: activate or not (required) - is the endpoint activated or disable
Service profile (required) - ID of the Service Profile assigned to the endpoint.
Tariff profile (required) - ID of the tariff Profile assigned to the endpoint.
You can add another optional informations, and be sure of the structure of your endpoint.
Hope this helps you.
I have been able so far to create a new civi Mailing object and populate it, but confusingly I can't see a parameter in that to specify the mail destination group.
For context, I am dealing with Civi using pure REST api from a remote server. I have a solution to getting a custom template onto the server; the new problem is setting a schedule and delivery group, and initiating the send. I am using the python-civicrm library from github as the intermediary on the client.
I presume send happens as a result of setting the schedule -- i.e. I don't need an API call to say 'send mailing'? Is setting 'sheduled date' == 'now' safe or should I set a date of 'now + 1min' or similar?
So that leaves setting the delivery group. We already have groups defined in the DB, and I want to specify the group by name (and preferably be able to verify in advance that a group name is a valid destination, perhaps by doing a group name -> id lookup).
I think there might be a parameter to Mailing create 'groups' which can have keys 'include' and 'exclude'; at least, that's what the web form seems to do. However it's not mentioned in the REST api implementation.
Can anyone offer pointers?
I think you will find all you need in the following link :
Example of api call that is using the group include/exclude : https://gist.github.com/xurizaemon/6775471
Discussion about implementing mailing as an api - http://forum.civicrm.org/index.php?topic=24075.0
Otherwise, if it doesn't work, i suggest that you :
help adding this api in the CiviCRM Core - you could have some help on this on irc #civicrm (and have a look at https://issues.civicrm.org/jira/browse/CRM-11023)
OR create an extension with the api you need. It will be automatically available for REST. If you haven't created an extension yet, i suggest you go to the page http://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension. It's quite straightforward with civix installed.
The table you need to check in the database is civicrm_mailing_group
To confirm, the problem was that (a) I needed to use groups[include]=array(ids) as mentioned by samuelsov, but also (b) I needed to use the json={...} form of request through REST, because the HTTP params syntax doesn't support nested data.
This is a classic RESTful way of creating resources I have in the application:
# This creates user. Client is responsible to create UUID, which is simple
PUT /users/CLIENT_GENERATED_UUID
# Access user by uuid
GET /users/UUID
When we touch the field of data storage performance it turns out that randomly generated UUIDs do not serve well by many reasons like data locality.
Server-generated IDs are good for performance but they don't really match REST:
If you use POST to create resources, you lose idempotency: PUT, GET, DELETE idempotency is implied by REST, while POST is not.
You may ask server to provide you with a nice ID before doing PUT. Despite it feels quite heavy and non-obvious, it also does not protect from dummy client that uses own random id instead of asking for it.
Could somebody give me a hint in this architecture matter?
Creating a resource using is not meant to be idempotent. If the server assigns the ID, it must choose a different ID for every resource to be created. Such an operation must not be idempotent, repeating it must create a different resource.
Using POST against a collecton resource as in
POST /users
is totally RESTful if the server assigns the ID. This request can be repeated and it will create a different resource.
Using an idempotent operation like PUT for creating a resource only makes sense if the problem domain allows the client to control the ID. I think that is ist not true for most domains.
My advice: use POST and let the server assign the ID.
Actually when you read RESTful Best Practices you can find that:
The POST verb is most-often utilized for creation of new resources.
in addtion to:
PUT can also be used to create a resource in the case where the resource ID is chosen by the client instead of by the server.
In REST environment you send POST to create resources and can return the server generated ID to send the values after with PUT or PATCH.
POST /users
PUT /users/id
Also, people create resources with PUT using client generated IDs
PUT /users
But I think the best aproach is use server generated IDs with POST.
Here are a clear explanation: http://www.restapitutorial.com/lessons/httpmethods.html
There is a gazillion of questions about RESTful interface naming conventions, esp. around singular vs plural resource names. A somewhat convention is:
GET /users Retrieve collection of users
GET /users/{id} Retrieve user
POST /users Create user
PUT /users/{id} Update user
DELETE /users/{id} Delete user
However, the above does not work when resource is a value derived from the environment.
My hypothetical application has the following endpoint:
GET /source Get information about the source of the query.
That responds with:
Referrer URL
Remote IP
Since source is derived from the environment, there is never more than one source, therefore calling the resource sources or providing sources/{foo} lookup is not practical.
Does REST style propose how to handle naming of these entities?
Dr. Fielding notes in section 6.2.1 of his famous dissertation :
..authors need an identifier that closely matches the semantics they
intend by a hypermedia reference, allowing the reference to remain
static even though the result of accessing that reference may change
over time.
Therefore, it makes sense to use plain source endpoint.
It would be a different thing if you wanted to provide more general service around IP address provided, like this one.