I'm building an API centric web application.
Our frontend will consume the API and after testing our plan is to release the API to the public.
I'm faced however with problems that in a normal MVC application were pretty straight forward but I can't seem to wrap my head around it in a RESTful way.
Take this example for instance:
A company has multiple office sites which point to a specific address
This address can be shared by multiple sites so Company has a one to many relationship with sites and sites has a many to one relationship with Address
When you update an address I'd like to let the user confirm that for that they either want to update the LOCATION (so all companies that share that location through Site will be updated) or they just made a typo and want to create a new Location
How would I go about this in a RESTful way?
I can do a
I first do a GET if there are other companies using that location
Then I give the user a choice either to do POST (create new location) or do a PUT (update location)
In case of POST also create a new Site linking the new location to the Company.
An other example is if what appears a single form for the user will invoke several different backend entities that have to update.
Any examples or ideas?
In REST, you might thing of the remote service as being the database. If you know how to do it in a generic MVC workflow, for fat-client apps it's the same.
You may want to deal with it on a "try default behavior, and raise attention if not possible" way, or with a "check what's possible and then offer possibilities". It's your app, it's your choice.
Personally, I'd go with a "try default and raise error if edge conditions happen". So in this case, assume (in the client) there is no other company with the same address, and use the corresponding endpoint (PUT). If the server detects a possible conflict, then return some error. The client will then prompt to the user what to do, and use whatever endpoint is chosen (POST or PUT, with a flag that enforces the update)
Related
I've been using Netlify for storing 100% of my app (both frontend and backend) for the last three months. So far, so good.
The only problem now is that I need to store a custom property for each user (say, the phone number), and apparently Netlify Identity doesn't support this (only email, name and roles https://www.netlify.com/docs/identity/).
I don't want to change the whole app to migrate to another hosting provider just for this detail (actually, I can't, it's for a client and I just don't have time), because it works great, but at the same time I need it.
Can you think of any workaround to this? The less "hackish", the better, but I understand that I'm going beyond the intended use of Netlify Identity.
So it actually does look like Netlify's GoTrue API has a specific endpoint for updating custom user data. After a user is created, you can update metadata by including it as "data" within an authenticated PUT request to /user.
PUT /user
{
"data" {
"custom_key": "value",
}
}
See https://github.com/netlify/gotrue for more info.
There are dozens of ways to do this, so I'll talk about two generally applicable ways now:
the most "generally capable" one is probably using lambda functions: https://www.netlify.com/docs/functions . This lets you run dynamic code, such as "store to database hosted elsewhere" or "email to our office manager to update a spreadsheet" or even "commit to our closed git repo so it's available in-code" (last one is probably a worst practice, but is possible). You can similarly use a function to read that data back out without exposing API tokens (code example: https://github.com/netlify/code-examples/tree/master/function_examples/token-hider)
you could have the data gathered via a form submission (https://www.netlify.com/docs/form-handling). I'd probably use zapier.com to receive a notification of the form submission (https://www.netlify.com/docs/form-handling/#notifications). Zapier can of course connect to just about anything on the planet :) . Getting the data back out if you want to show it in your UI is a bit more of a challenge, but you could use the above mentioned functions if you need to connect to some private data store to pull it out. Or for an MVP, just not show it, only let people enter/update it ;)
We have a single-page app (AngularJs) which interacts with the backend using REST API. The app allows each user to see information about the company the user works at, but not any other company's data. Our current REST API looks like this:
domain.com/companies/123
domain.com/companies/123/employees
domain.com/employees/987
NOTE: All ids are GUIDs, hence the last end-point doesn't have company id, just the employee id.
We recently started working on enforcing the requirement of each user having access to information related exclusively the company where the user works. This means that on the backend we need to track who the logged in user is (which is simple auth problem) as well as determining the company whose information is being accessed. The latter is not easy to determine from our REST API calls, because some of them do not include company id, such as the last one shown above.
We decided that instead of tracking company ID in the UI and sending it with each request, we would put it in the subdomain. So, assuming that ACME company has id=123 our API would change as follows:
acme.domain.com
acme.domain.com/employees
acme.domain.com/employees/987
This makes identifying the company very easy on the backend and requires minor changes to REST calls from our single-page app. However, my concern is that it breaks the RESTfulness of our API. This may also introduce some CORS problems, but I don't have a use case for it now.
I would like to hear your thoughts on this and how you dealt with this problem in the past.
Thanks!
In a similar application, we did put the 'company id' into the path (every company-specific path), not as a subdomain.
I wouldn't care a jot about whether some terminology enthusiast thought my design was "RESTful
" or not, but I can see several disadvantages to using domains, mostly stemming from the fact that the world tends to assume that the domain identifies "the server", and the path is how you find an item on that server. There will be a certain amount of extra stuff you'll have to deal with with multiple domains which you wouldn't with paths:
HTTPS - you'd need a wildcard certificate instead of a simple one
DNS - you're either going to have wildcard DNS entries, or your application management is now going to involve DNS management
All the CORS stuff which you mention - may or may not be a headache in your specific application - anything which is making 'same domain' assumptions about security policy is going to be affected.
Of course, if you want lots of isolation between companies, and effectively you would be as happy running a separate server for each company, then it's not a bad design. I can't see it's more or less RESTful, as that's just a matter of viewpoint.
There is nothing "unrestful" in using subdomains. URIs in REST are opaque, meaning that you don't really care about what the URI is, but only about the fact that every single resource in the system can be identified and referenced independently.
Also, in a RESTful application, you never compose URLs manually, but you traverse the hypermedia links you find at the API endpoint and in all the returned responses. Since you don't need to manually compose URIs, from the REST point of view it's indifferent how they look. Having a URI such as
//domain.com/ABGHTYT12345H
would be as RESTful as
//domain.com/companies/acme/employees/123
or
//domain.com/acme/employees/smith-charles
or
//acme.domain.com/employees/123
All of those are equally RESTful.
But... I like to think of usable APIs, and when it comes to usability having readable meaningful URLs is a must for me. Also following conventions is a good idea. In your particular case, there is nothing unrestful with the route, but it is unusual to find that kind of behaviour in an API, so it might not be the best practice. Also, as someone pointed out, it might complicate your development (Not specifically on the CORS part though, that one is easily solved by sending a few HTTP headers)
So, even if I can't see anything non REST on your proposal, the conventions elsewhere would be against subdomains on an API.
A quick api uri design question. We have resources that belong to our clients. These resources can be edited / viewed / deleted by the client who entered them into our system. The resources can be searched by all clients but access is only granted if certain criteria is met (client has level 3 access etc).
Choice 1: include the client who owns the resource in the uri.
client/:clientname/widgets
client/:clientname/widgets/:id
Choice 2: ditch the whole "client/:clientname" since this part of the uri has to be verified and checked against the credentials of the user accessing the information.
/widgets
/widgets:id
We have other resources other than widgets that also belong to clients.
Which way is the more preferred way and why? Cheers.
The only advantage that Choice 1 gives it that it allows you to effectively namespace widgets/whatever by the user that uploaded them. Similar to Github, how different users can have projects with the same name. If Github were to exclude the username, no two users could have a project with the same name. If the widgets are all unique, I would go with option two and you will have a 1:1 mapping from a widget the the user that created it, thus supplying it is just extra work for whoever is calling it.
If you can have the same widget name for different users, use an approach which includes the username. You may not need to actually use the 'client' word in your url though; using a path like '/:clientname/widget/:widgetid' instead.
Note that this is kind of an opinion based question, so you may get different answers. You'll have to weigh the information provided and in the end make your own decision.
Question
How do we make a resource not a verb... but still maintain its special actions outside the default GET, POST, PUT, DELTE actions?
Details
I have been searching for some time now about the proper way to build a RESTful API. Tons of great information out there. Now I am actually trying to apply this to my website and have run into a few snags.
What our site does:
Our site site allows people to play games and win prizes.
The API will allow developers to build their own games and use our backend to collect, validate, store user information and give out prizes.
Scenario:
Developers will create their game then make a call to our API to let the player play the game (play_game). This play_game method combines multiple functions that we do not want a developer to run independently.
Here is what a play_game call does on the server:
It accepts player data the developer wants to store.
Validates the data (compares it to rules setup in the control panel)
Calculate what prize should be given.
Returns what prize was won to the Developer.
In addition there are multiple functions behind the scenes that get triggered like sending emails, etc.
Resource This is what our current resource looks like:
http://site.com/api/play_game
Issue:
This doesn't hold to the idea of no verbs in RESTful API's.
How do we make this resource not a verb... but still maintain its special actions outside the default GET, POST, PUT, DELTE actions?
Notes:
After asking this question I have decided to use Phil Sturgeons RESTful Framework... unless someone has a better idea.
You could place the following code into applications/routes.php
$route['(.*)'] = 'api';
Then you could access your API like:
http://site.com/play_game
BUT
You'll only have access to ONE controller only (your api controller)
Hope it helps
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.