So I know this is crazy from a security standpoint, but let's say I have a posts resource at /posts/ and I'd like an admin to be able to trigger a transformation on the collection (in this case, a simple data migration).
How should I design the URL for something like that? It's basically a remote procedure: "take all the posts, modify them, and save them", which is why it is hard to shoehorn onto REST.
I ended up just doing POST /posts/name-of-transform. It's going to be hacky either way :(
So what you want is to update a collection right?
I think what you're looking for is the http PATCH method. It will acte pretty much like your POST method but instead of creating the ressources it will update them.
You can find more about the PATCH method at this address : https://restful-api-design.readthedocs.org/en/latest/methods.html
Related
I'm trying to make API calls to my web hosting (ovh) in order to create email alias and email accounts.
Some years ago I did that in Cakephp2 using Datasource, but now I'm using cakephp4 and I'm not sure how to proceed...
How can I create a Model without a database Table ?
My advice would be to just not go down that route, IMHO you'll be much better off if you create a simple custom service around the API instead, there's no need to make all datasources look like CakePHP database/ORM "repositories" (I put that in quotes because CakePHP's repositories should not be confused with what repositories are in the context of the repository pattern).
If there was really, really, really a need for it, I'd say first go look into muffin/webservice, which shoulders some of the work required for you. And if you wanted to know how to do it completely on your own, well you'd have to implement \Cake\Datasource\RepositoryInterface accordingly, which comes with lots of baggage and is anything but straightforward.
If you want to see how that could look like, I'd again refer to muffin/webservice, check for example its Endpoint repository and the surrounding classes, that should give you an idea of the "how to" and the complexity involved.
I'm new in API developement and I wanted to know what is the best choice to create pagination :
GET resquest with query params (sort, limit, etc)
POST request with params in the body (sort, limit, etc)
I was more on the GET but my coworkers thinks POST is a better choice, so I just wanted your opinion.
GET would be the usual choice.
General purpose components will understand that the semantics of GET are safe, which means they are also idempotent. If a GET request receives no response, you can automatically retry it without any concerns about loss of property.
Furthermore, if all of the information you need to identify the resource is included in the URI, then you can bookmark the URI, or paste it into an email, or link to it in a document, and it will all "just work".
Also, using GET -- with all of the relevant details encoded into the resource identifier -- means that the response can be cached and re-used. The constraints on caching POST requests mean that you can't capture the information in the request body.
At some point in the future, HTTPWG will register a new HTTP method to cover the safe method with a body case, which may change some of the answers.
In the meantime, it is okay to use GET.
GET is the recommended way to do this, because the answer can be cached and the goal is reading not writing. You can use the query string or range headers for pagination. The exact solution depends on your needs. There are a few standard query languages for this, like OData, but they are overkill for a simple API. Building a custom solution on top of URI templates might be a better choice, or there are non-standard query languages too like RQL, which can be completely or partially implemented in your solution.
I'm creating a set of RESTful API and I have this question: I have a resource that has some images attached and I'm creating my resources like this:
POST to /resource: create the object and save the images to the server.
GET to /resource returns the object but no the images, GET to /images returns the images.
My question is: is this compliant with REST or should I either make the resources completely separate or completely unified?
I choose this solution because when posting I for sure send the images, but I may need them or not when doing a get.
is this compliant with REST
It's fine - for instance, if you look at the way that Atom Publishing works, you'll see that when you post a media to a collection, two resources are created (the Media Resource and the Media Link Entry).
However, fine here means you are making tradeoffs. In particular, cache invalidation is more challenging when you a POST to one resource may change the representation of a different resource.
HTTP caching semantics are optimized for the common case, which is that a given request changes only the target resource; no spooky action at a distance.
That doesn't mean that this is the Right Way, but rather that you should understand that this is the way that HTTP makes easy, and in other cases you need to pay attention to the details.
POST can basically mean anything, and unlike PUT and GET (for which there is a bit more of a direct relation), POST is allowed to result in all kinds of side-effects, including the creation of 0 or more resources.
POST is basically the 'anything goes' method.
I'm a new REST convert and I'm trying to design my first RESTful (hopefully) api and here is my question about addressing resources
Some notes first:
The data described here are 3d render
jobs
A user (graphics company) has multiple projects.
A project has multiple render jobs.
A render job has multiple frames.
There is a hierarchy enforced in the data (1 render job
belongs to one project, to one user)
How's this for naming my resourses...?
https:/api.myrenderjobsite.com/
/users/graphicscompany/projects
/users/graphicscompany/projects/112233
/users/graphicscompany/projects/112233/renders/
/users/graphicscompany/projects/112233/renders/889900
/users/graphicscompany/projects/112233/renders/889900/frames/0004
OR a shortened address for renders?
/users/graphicscompany/renders/889900
/users/graphicscompany/renders/889900/frames/0004
OR should I shorten (even more) the address if possible, omitting the user when not needed...?
/projects/112233/
/renders/889900/
/renders/889900/frames/0004
THANK YOU!
Instead of thinking about your api in terms of URLs, try thinking of it more like pages and links
between those pages.
Consider the following:
Will it be reasonable to create a resource for users? Do you have 10, 20 or 50 users? Or do you have 10,000 users? If it is the latter then obviously creating a single resource that represents all users is probably not going too work to well when you do a GET on it.
Is the list of Users a reasonable root url? i.e. The entry point into your service. Should the list of projects that belong to a GraphicsCompany be a separate resource, or should it just be embedded into the Graphics Company resource? You can ask the same question of each of the 1-to-many relationships that exist. Even if you do decide to merge the list of projects into the GraphicsCompany resource, you may still want a distinct resource to exist simple for the purpose of being able to POST to it in order to create a new project for that company.
Using this approach you should be able get a good idea of most of the resources in your API and how they are connected without having to worry about what your URLs look like. In fact if you do the design right, then any client application you right will not need to know anything about the URLs that you create. The only part of the system that cares what the URL looks like is your server, so that it can dispatch the request to the right controller.
The other significant question you need to ask yourself is what media type are you going to use for these resources. How many different clients will need to access these resources? Are you writing the clients, or is someone else? Should you attempt to reuse an existing standard like XHTML and classes/microformats? Could you squeeze most of the information into Atom? Maybe Atom with some extra namespaces like GDATA does it? Or is this only going to be used internally so you can just create your own media types, like application/vnd.YourCompany.Project+xml, application/vnd.YourCompany.Render+xml, etc.
There are many things to think about when designing a REST api, don't get hung up on what your URLs look like and you should really try to avoid doing "design by URL".
Presuming that you authenticate to the service, I would use the 1st option, but remove the user, particularly if the user is the currently logged in user.
If user actually represents something else (like client), I would include it, but not if it simply designates the currently logged in user. Agree with StaxMan, though, don't worry too much about squeezing the paths, as readability is key in RESTful APIs.
Personally I would not try to squeeze path too much, that is, some amount of redundant information is helpful both to quickly see what resource is, and for future expansion.
Generally users won't be typing paths anyway, so verbosity is not all that bad.
I'm a big fan of keeping application logic in the servlet, and keeping the JSP as simple as possible. One of the reasons for this is that any good web designer should be able to expand upon his HTML knowledge to build in a few JSTL tags to do simple iteration, access beans, etc. We also keep the more complex/ajax/js components behind a tag library (similar to displayTag but for our own components).
Most of the time everything works out ok - The servlet does any SQL it needs to, and stores the results in beans for the JSP to access. Where we have a problem is when the records we wish to access are specified by the design.
The clearest example would be the home page - it needs to be eye-catching and effective. It doesn't need to be uniform like rest of the site. There are lots of one-offs or "special cases" here, where we want to query a particular product record, or whatever.
What the designer really wants is a way to get a product bean by the product id so he can access the properties as normal. We obviously don't want to query for all products, and I don't want to query in the presentation.
I'm pretty sure I'm asking the impossible here and that I have to give something up. My question is what?
EDIT
Am I wrong in thinking that all application logic should be complete before calling the JSP? I was under the impression it was considered best practice to do all querying/calculating/processing in the servlet then pass (fairly) dumb beans to a (very) dumb JSP.
There are a couple of methods whereby the actual complexity of the query can be encapsulated in another class (custom tag or bean), and the JSP can call it. This
keeps the JSP simple (goal 1) but the JSP is still "triggering" the query - quite
late in the process.
Have I got this totally wrong and it's fine to do this.
Is it a general rule, but perfectly ok to do this in this instance.
Might I run into problems?
EDIT - Example
I'm hoping this example will help:
The home page isn't a "template" like the category/search pages - it is custom designed to work very well with say a marketing image and a couple of specific product images. It does however have information about those two products which should be obtained dynamically (so the name, and importantly price) stay in sync with the db.
The servlet can't know which products these will be, because if the designer wants to change them/remove them/add more, he should only have to edit the JSP (and possibly XML as one answer suggested).
If I understand correctly, you have logic in the JSP that wants a particular product, but at this point you don't want to query from the DB, and its too late for the servlet to be aware of it.
(A side note, while I respect your will to maintain separation of concerns, the fact that this is an issue clearly shows that your framework has too much logic in the presentation tier...but since we probably can't fix that...moving on).
My recommendation is that your designer creates a configuration XML file that contains whatever special cases it needs for the frontend, and yours servlet can read that, then pass dumb beans back to the JSP.
OR...you break things down into multiple requests using XMLHTTPRequest and call back to the servlet for each individual query, then assemble the page on the client.
It sounds like you need better separation between the display and database code. You should have separate classes that just deal with interacting with the database, and know nothing about display.
Then you just create a method that will look up the product by id and return that bean so the display can pull out the attributes it wants.
You need to create a custom bean which will perform your queries for the front end. Actually, it's probably more like a few beans to get the data for you, according to what you say here.
There's no problem with doing that from a design perspective; it's just that the specific design of the home page has more heterogenous requirements than the rest of your site. Make sure your designer knows that he needs to communicate his needs well to the development team to create the BO for your homepage (or whatever) and thing should go fine.
You are not wrong in thinking that all application logic should be complete before rendering the JSP.
If there is a need to fetch more stuff for displaying in your JSP, it would be another request to the server and another Page cycle. If you are looking for 'interactive' loading experience, you could use AJAX.
In a single page life-cycle, I find it hard to understand why do you have to invoke database calls from a JSP. Hasn't the page been previously posted with all the required form variables to help you find the data in Servlet/Helper classes?
If you could give an example of a case, it would be helpful.
[Edit] Looking at your example, yes your designer (or the admin of the site) should set that information as a configuration, not a part of JSP. Or, you could have a small app/admin page to maintain the information in a database so that it could be changed on the go. When you show your homepage, read the configs and load the appropriate data.
I am not sure what is the question. I f you want to have sql statements out of your jsp pages then you can put them in a property file and just read the property file from the jsp page.