CODEWITHSUNDEEP
apirestresources
RP.
RP.

Reputation: 13

Suggestions on addressing REST resources for API

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:

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!

Upvotes: 0

Views: 645

Answers (3)

Darrel Miller
Darrel Miller

Reputation: 142044

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:

alt text

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".

Upvotes: 2

Deeksy
Deeksy

Reputation: 5434

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.

Upvotes: 1

StaxMan
StaxMan

Reputation: 116502

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.

Upvotes: 0

Related Questions