i am a rails programmer who is on to his 3rd project now (new of course).I am looking for an answer to a general question about Restful architecture. I am sure i am doing something that has a good established answer already.
In restful approach we expose resources but some times this approach feels a little Non user friendly. For example i can expose a product via a show method and then i have another resource called sales that i can expose via product/:id/sales show template to show all sales for a product. But i am taking the user through an extra click here. The ideal will be to show product and all its associated sales on one page itself. But that is a violation of the Restful rule.
I just wanted to ask that are these rules generally broken to make the site user friendly? Being a new comer i dont want to adopt ways that are non ideal so i thought i should ask this question.
Thanks in advance.
Adding in the sales for a particular product would not be breaking any constraints from the RESTful architecture. You have the product ID in the HTTP request so you can just also get the sales for that product. Your separation of concerns should not be affected and you don't need to store a state to get this information. Just extend the model that you return with the view.
It seems like you are more concerned with straying from the convention over configuration that Rails promotes. This extension means that your model will not correlate with only one table in your database, but that is fine. The conventions are meant to reduce the configuration work that you need to do, not restrict your functionality.
Related
Ok, my last question had no answers, so I've the doubt that I'm walking on the wrong way.
I'm developing some Web REST Api for a mobile application, and regarding REST best pratices I don't know how to face a many-to-many relationship.
I have two tables, Wallets and Cateories, between these tables there is a many to many relationship since a category may be associated to different wallets and a wallet may own different categories.
Actually this database is used by a non rest website:
when a user creates a new category, he choose from the list of his own wallets which wallets to connect it to, and with this single POST call the category is created and conneted to the wallets.
I don't think that replicating this behaviour is compliant to REST best pratices.
My first idea was to "expose" the connection between categories and wallets with this form:
http://localhost:8000/categories/77/wallets/4
but I had the problem I wrote on my previous question, and I don't think this is the right way.
Anyone has a valid method to manage a many-to-many realtionship according with REST best pratices?
Thanks in advance.
Namespacing wallets by a category is fine, as in /categories/77/wallets/4. You can also consider a more concise scheme like /categories/77/4 or /wallets/77/4 if there are only wallets in a category.
However, you don't have to namespace. Your wallets presumably have their own IDs, so you could also just expose them as /wallets/4.
Is it worth the effort? I think it can be a good practice if your URLs are also on a public website (in which case you would probably want to support slug IDs as well, e.g. /categories/luxury/wallets/acme). If not, you should be aware it will be a little more configuration work on the server-side and a little more work for clients (clients will have to be aware of 2 IDs instead of 1).
We have an app which is exposing a RESTful API to a UI for purchasing an item. I have a question regarding API design. Lets say the following action should be taken in order
Item to be chosen for purchase
Next give the address to be delivered to
My question is: should we design a single API which gets both data perform both? Or should we design two API calls - one that creates a purchase record and second that update the address to be delivered to?
The recommended SOA approach is to choose coarse-grained services, which would seem to argue the minimum amount of API calls.
However, from a business point of view, item selection and purchase and item delivery are two very different concerns that should be separate components in your architecture. For item selection, you need to consider things like inventory and pricing. For delivery address, you need to consider user address lists, address validation, shipping, and taxation.
Those two components are not likely to interact much except maybe some external association between an item id and address id. For this reason, I'd recommend two API calls. Functionally, this would also allow your API users do things like update the delivery address without re-purchasing an item, send the bill to one address and the item to another address, etc.
As you state that you design a RESTful API you usually start by designing resources instead of the intended calls. Later on, resource representations can be chosen that include other resources for optimised HTTP request counts.
You might want to choose to proceed the following way:
Model the item list resource (GET - lists all items, POST - allows item creation) /items/
Model the address list resource /addresses/
Model the item instance resource /items/item/resourceId
Model the address instance resource /addresses/address/resourceId
Now all of your resources are available you can think about usage patterns. All your resources are generically available and can be mashed up.
Possible approaches to answer your questions would be:
Extend the item instance resource with the needed address details (coarse grained as lreeder stated)
Model a resource /deliverydetails/ as list and instance resource containing item(s) and address, make the deliverydetails to be queried by item id or whatever your use case fits best
Hope that helps!
Btw. you are automatically following SOA approaches with a Resource Oriented Design. Interfaces will be naturally fitting your business requirements and generic enough to support more advanced use cases.
Here is a good example
I'm building my first REST API (at least trying) for a personal project.
In this project there are resources called players which hold can be in a team. According to REST API design rulebook a resource should be made either to be a document or a store and one should keeps these roles as segregated as possible.
Yet I would like to append some metadata to the team resource, eg the date the team was founded. Is it okay then for GET /teams/atlanta to return this metadata (making it a document) alongside the list of players in the team (making it a store).
Is this a good idea? If so why? If not why not and how to solve this better?
I know there are no rules to developing a REST API, but there are good practices and I would like to adhere to those. Please also not that this is really my first REST API so pardon my ignorance if there is any.
I would recommend having GET /teams/atlanta return just the information about the team, such as the founding date that you mention, and then having GET /teams/atlanta/players return the list of players for that team. These distinctions become more important when you are presenting an API that uses HTTP methods other than GET.
For example, if you wanted to add a player to a team - this would be a lot easier if you could just POST a player object to /teams/atlanta/players than if you had to PUT the whole team object to /teams/atlanta every time you wanted to add one individual player.
If your API only allows retrieval of data, and if it is for a specific client application, there is an argument for combining all the team data into one object to save the client having to make additional requests for the data, but bear in mind that it is less flexible.
Your application may want to display a list of teams by calling GET /teams but you probably wouldn't want all of the player information included in each object in the list as this is quite a lot of data, but if GET /teams/atlanta returns player information then it would be inconsistent not to include it in the list version too.
I would personally favour splitting up the resources as I've suggested, and live with the fact the client may need to make an extra request or two.
I'm developing a rest API for our business system. We have the following resources so far:
/sales/orders
/sales/orders/{orderno}
/sales/order-items
There will be lots of resources when the API is finished, so we need to structure it in a good way to make it easy to understand. My question is: should /sales/order-items instead be /sales/orders/order-items? There is maybe no correct answer here, but what would you prefer?
One more question: The sales/order-items resource will list either all open items or all shipped items. It will not be possible to get all order-items regardless of status (open/shipped). The resource URI could the be like this sales/order-items?orderstatus={OPEN/SHIPPED} (the orderstatus query parameter would be mandatory then) or it could be two resources like this sales/order-items/open and sales/order-items/shipped. What is the preferred?
A resource is 'any information that can be named'. Your URIs should be entity based. 'order-items' is not an entity, but a data type.
/sales/order/order-1456321 is the Entity you most likely want. Which would contain the data of all order items.
If you wish to restrict access, you can return a client error if no query string is supplied. and having
/sales/order/order-12345?status=open
etc. Hope this helps.
EDIT:
/sales/order-items or /sales/orders/order-items?
This is domain specific, and really should be answered by a domain expert. Your URI Hierarchy provides scope (and so detail) to your resource. So as an educated guess, It does not make sense to have "order-items" within the scope of "/sales/orders/" because "order-items" is not an "order".
/sales/ordered-items
seems the most sensible answer.
On a personal note, and not to question your domain too much, Having a strong understanding of the flow of the business and information that's stored may result in something along the lines of these suggestions;
/sales/orders?status=open - Are all orders shipped at once?
/sales/orders/order-1234/packages?status=open - Are orders split into packages?
EDIT: I've solved my issues (for now at least).
I've recently been working with the Zendesk REST Api and their use of the custom "X-On-Behalf-Of" header for looking up tickets opened by a particular user got me thinking about Restful Api design choices (in no specific language, more of a how to name URIs question). I've also read this related question on Custom HTTP headers, but it left me with more questions than answers.
Say I have an example restful web service dealing with rental apartment applications where clients use Basic Auth (keep it simple) to authenticate. Define the basic data as such:
Users (can be of type landlord or renter)
Forms (which consist of one or more Document resources and some form meta data like form name and version info)
And then some type of resource corresponding to Rental Applications, which ties together Forms, Applicants (one or more renters), Landlord, and some metadata like status and dates.
I'm struggling to properly model the URIs for the Applications resource in general, and more specifically with respect to a clients role. (assume api root is https://api.example.com/)
How do I allow a Landlord to fetch a list of applications sent to them? My intuition says make a request to "GET /applications" and Basic Auth lets the server know which user to build the list for; likewise "GET /applications" requested by a Renter would return a list of applications they've sent...but I'm not confident this is a solid design in general to mix and match sender vs. recipient lists at the same URI. Should I be thinking about the "/applications" resource differently, and perhaps allowing a hierarchy like "/applications/[USER_IDENTIFIER]" for each user instead?
Also, regardless of my applications URI design, assume a Landlord is able to create an application on behalf of a renter. Is this better accomplished by sending a custom header like "X-Create-On-Behalf-Of: somerenter#example.com" with the PUT/POST creation request? Or should my schema define a field which allows for this alternative scenario.
I'm very much an amateur at this, so I'm open to any criticism of my assumptions/design, as well as any pointers for learning more about designing RESTful api's. Thanks for reading.
I think I've found a solution.
Landlords and Renters are really just subclasses of the same object, which I'll call Party (as in party to a transaction, not birthday party). So then each one has their own resource, named like /party/PARTY_ID.
It's easy to extend this to see that /party/SOME_LANDLORD/applications and /party/SOME_RENTER/applications solve my issues. It also removes my need to consider custom headers.