I'm adding a new REST service to our API, and wanted to canvas a few opinions on the best REST API. The service is used to retrieve the user's email address in case they have forgotten what their username is. The service requires three parameters:
Account number (this is a number that is on their printed statement)
Surname
Date of birth
If we find a match for these three pieces of info, the service returns JSON contained a masked version of the user's registered email address (eg. jo******#gmail.com) so that the UI can present a message something like "We are going to send your username to j******#g******.com. Is that OK?"
Note that the service doesn't actually change anything within their account or send an email (it is purely fetching info so that the user can confirm the next step), so it seems to me that a GET request is the way to go. The question is how to represent it? It strikes me that /users is a reasonable place to start(?), but then what? Using the URL path, I might end up with something like:
/users/accountEmail/accountNumber/123456/surname/Smith/dateOfBirth/25-12-1970
This seems icky as, ordinarily, our /users URLs contain the username (eg. /users/john/transactions), but clearly for this API call we don't actually know who the user is yet. I'm also not sure it really indicates what the service actually does. Alternatively, I could use URL query params:
/users/accountEmail?accountNumber=123456&surname=Smith&dateOfBirth=25-12-1970
This feels a bit more natural, but I'm unsure that stringing all those input parameters into the URL is a good idea. Then again, maybe /users is the wrong noun. Maybe it should be like:
/accountEmail/...
Having said all that, maybe given the service's idempotence, I could actually use a PUT request and encode the parameters into the HTTP body. Not sure about using PUT for read-only requests though... it seems a bit like heading down the RPC path. The one nice thing about the PUT approach though is that it doesn't log this relatively sensitive user input into any web server logs.
I'd be interested in opinions or hearing what other API developers did in a similar situation. Thanks.
First of all, don't use method GET with sensitive information in URL parameters or in a URL path, because that information can be stored in web server access log files, browser's history, HTTP proxy log files, etc.
Security wise you need to use method POST in this case. In regard of URL to use, I'm not that sure, probably something like /accounts and put all parameters to the request body.
Your second approach is what I would use. Logically, the URLS are build following these steps.
Collection Resource of Users
The URL
GET /users
returns a list of all users including all user properties.
[
12345: {
"surname": "Smith",
"firstname": "John",
"dateOfBirth": "1970-12-25",
"accountEmail": "john.smith#example.com"
},
6789 : {
"surname": "Hallow",
"firstname": "Jane",
"dateOfBirth": "1981-02-15",
"accountEmail": "jane.hallowh#example.com"
}
]
Sub-Collection Resource of User Emails
The URL
GET /users/accountEmail
returns al list alf all emails for all users.
[
12345: {
"accountEmail": "john.smith#example.com"
},
"accountEmail": "jane.hallowh#example.com"
}
]
Filter this Resource
The URL
GET /users/accountEmail?accountNumber=123456&surname=Smith&dateOfBirth=25-12-1970
returns a filtered list of emails for the users that match the query parameters.
[
12345: {
"accountEmail": "john.smith#example.com"
}
]
Related
I am trying to figure out the best way of adding multiple users to a group via a REST API.
Right now, I am thinking this is the best way of adding a single user at a time:
PUT /groups/123/{userID}
Then, to remove the user from the group:
DELETE /groups/123/{userID}
But how would I add multiple users to the group at the same time? Would this be the best way?
PUT /groups/123
Content body as an array:
[
"user1",
"user2",
"user3"
]
...and to remove the users from the group, I would do the same thing via a DELETE request.
Is there anything "wrong" with this setup, or would there be a better, more "industry standard" way of doing this?
How to PUT multiple resources via a REST API
You don't do that - each request in HTTP has one-and-exactly-one target resource; the semantics of the PUT request are that the message body of the request is a replacement representation for the resource.
Resources are generalizations of documents.
It's entirely reasonable to have a document that is a representation of the members of some group.
PUT /groups/123
[
"user1",
"user2",
"user3"
]
What this request means is "replace your copy of /groups/123 with this copy". It's purely a document editing command.
The useful work - like actually making changes to the master group membership list, is a side effect of making your copy of the document look like the provided copy. See Webber 2011.
In this style, "removing" a user from the group would look like another edit to the /groups/123 document
PUT /groups/123
[
"user1",
"user3"
]
Of course, remote authoring semantics aren't required; you could instead do:
POST /groups/123
Please remove user1
or
POST /groups/123
action=addUser&id=user4
to remove the users from the group, I would do the same thing via a DELETE request
Careful - DELETE (like PUT) means something specific in HTTP, and that may not be what you mean.
Relatively few resources allow the DELETE method
The semantics of DELETE belong firmly in the transfer documents over a network domain, not in the "manage users and groups" domain.
I am wondering if implicitly using the currently authenticated user as context for API interactions is RESTful or not. For example, assuming all my API calls are authenticated using standard HTTP security:
Should a query to retrieve a list of orders for the user be explicit?
NO: http://example.com/orders
YES: http://example.com/orders?userid=1234
When placing a POST to create a new order, should the JSON contain the user?
NO: { orderref: 'EXAM/1', items: { ... } }
YES: { userid: 1234, orderref: 'EXAM/1', items: { ... } }
Either way I'll be securing so that the API will only allow actions for the current user, but should I make the API caller state the userid for each action?
I would say you should only pass the user ID as a query if you have access to many user's orders and need to filter them by user.
If a user has access to only their own orders they should not have to pass a user ID - the base queryset should limit it based on their own authentication details. Arguably that may not be RESTful, but don't worry about that - most API's may not be 100% RESTful and you should do what makes sense for your application rather than worrying about whether it's RESTful - it's a guide, not a cast-iron requirement.
In any case depending on what type of authentication you use (BASIC or TOKEN), you have to send the user info in your API call (Headers) which makes the request to the API.
So when you say if it is valid to use the authenticated user from the Context, of course it is
sample code here
The api call
headers.Authorization = 'Bearer ' + localStorage.getItem("tokenkey");
Obtain user from the request
RequestContext.Principal.Identity.Name
Is it RESTful? I would argue that: yes it is. There is no REST spec, so there's nothing really that says that it isn't. HTTP does allow this, and HTTP Caches should actually by default consider responses to GET requests with an Authorization header as private.
Should you use this design? I don't know! I think there's benefits to having per-user endpoints, because in the future it might allow User A to inspect the orders of User B.
In our API we actually have an example of an API similar to yours, but we do both.
We have a /users/1234 endpoint.
We also have a /current-user endpoint.
Initially the /current-user endpoint just redirected to the uri of the actual current user, but eventually we decided we're actually just going to return the full object without redirecting (due to browsers not behaving nicely with redirects).
The current-user endpoint does have a self link still that points to the real user resource.
So to sum it up. I think you are in the clear here, but I argue that there are strong design benefits to creating resources that have a consistent representation regardless of who's looking at it. It makes things a bit simpler and nicer.
And also don't forget that there's no reason why you can't, if you are actually following REST. All a client should care about is that there's a link somewhere to a list of orders and it shouldn't care what it's url is.
+1 for Matthew Daly's answer. Especially when the authenticated user has only access to his own orders (I assume that).
In case that your authenticated user can access more order lists than only his own, I would go like that:
/orders: the authenticated user's orders.
/orders/123: the specific user's orders.
If 123 equals the authenticated user's id - so what? It would be most likely no problem case for your client.
By designing a REST service you think of the comfort that the developers could have, when they use your API. I would say, this one is a comfortable solution.
Should a query to retrieve a list of orders for the user be explicit?
NO: http://example.com/orders
YES: http://example.com/orders?userid=1234
When placing a POST to create a new order, should the JSON contain the
user?
NO: { orderref: 'EXAM/1', items: { ... } }
YES: { userid: 1234, orderref: 'EXAM/1', items: { ... } }
If user queries only its own orders, user id shouldn't be passed explicitly in the query - you should pass user token in HTTP header and your code should extract user id by provided token and determine whether authorized user has rights to see or modify particular data.
In case you want to let one user get or modify another user data then you would make additional endpoint - something like users/{userId}/orders or users/{userId}/orders/{orderId}. You would still pass user token via HTTP header and your implementation should check if user has admin rights for this action.
I'm making the following request against the Microsoft Live API:
GET https://apis.live.net/v5.0/me/picture?access_token=ACCESS_TOKEN
The result, unlike any other request to that API, is a redirect to a physical image location, which causes the actual image object to be returned instead of a typical JSON response that would include the path to that image.
I could dig into the the response object and try to get the Content-Location header or something to get the URL I'm looking for, but that feels very brittle and diverges from the way I'm handling every other API response.
I also know that the API URL itself, based on this behavior, can act as the image URL, but 1) I'm using a client that constructs that URL behind the scenes and 2) I don't want to persist the access token in something like a profile picture column.
The Interactive Live SDK actually shows a JSON object as the return for a REST request:
{
"location": "https://cid-0000000000000000.users.storage.live.com/users/0x0000000000000000/myprofile/expressionprofile/profilephoto:UserTileStatic"
}
That is the kind of response I want, and since the interactive SDK can show it, there's got to be some way to request that JSON be returned. I've tried setting redirect=false in the query string (necessary for Facebook, which does something similar) and setting the Accept request header to application/json. Neither had any effect.
This is not truly an answer to my question, so I'd still be interested any responses along the lines of my original question. However, I have found a workaround of sorts.
The URL https://apis.live.net/v5.0/{user_id}/picture will return the appropriate photo photo without requiring an access token. Therefore, all you need is the the user's id to construct this URL, and that can be obtained via:
GET apis.live.net/v5.0/me?access_token=ACCESS_TOKEN
Which will return something akin to:
{
"id": "0000000000000000",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"gender": null,
"locale": "en_US"
}
The id member there, is what you need for the URL. It's not ideal, because I have to sort of do two steps, and hope Microsoft doesn't change the way the profile picture for a specific user is retrieved or suddenly starts requiring an access token for that too. It's better than nothing, though, I suppose.
Adding ?suppress_redirects=true should do it.
i.e.
GET https://apis.live.net/v5.0/me/picture?access_token=ACCESS_TOKEN&suppress_redirects=true
I actually haven't tested this with /me/picture, but {user_id}/picture has the same behavior and adding suppress_redirects=true did the trick.
I was reading this Questions regarding REST
What exactly is RESTful programming?
While reading i get that the client is independent of server and client don't need to construct anything.
I want to know that when we are building forms like user registration . Then what is the REST way of doing it.
I mean when i do GET for /user/new then
Does the server has to send the complete FORM in html
Only send fields in JSON and form is constructed by client itself
But then again there will be many complexities, if i just send the fields, then what things like
Hidden fields
Default value for select boxes
what about some logic like this field can'r be greater than 30 etc
REST is, as you're already aware, a way of communicating between a client and a server. However, the issue here is what is being defined as the "client". Personally, I tend to consider that the browser itself is not in itself the client: instead, the client is written in JavaScript, and the browser is merely a conduit to executing it.
Say for the sake of argument that you wish to view the details of user '1414'. The browser would be directed to the following location:
/UserDetails.html#1414
This would load the static file ViewUser.html, containing all the form fields that may be necessary, as well as (via a <script> tag) your JavaScript client. The client would load, look at the URL and make a RESTful call to:
GET /services/Users/1414
which would send back JSON data relating to that user. When the user then hits "save", the client would then make the following call:
PUT /services/Users/1414
to store the data.
In your example, you wanted to know how this would work with a new user. The URL that the browser would be directed to would be:
/UserDetails.html#0
(or #new, or just # - just something to tell the JavaScript that this is a new client. This isn't a RESTful URL so the precise details are irrelevant).
The browser would again load the static file ViewUser.html and your JavaScript client, but this time no GET would be made on the Users service - there is no user to download. In addition, when the user is saved, this time the call would be:
POST /services/Users/
with the service ideally returning a 302 to /services/Users/1541 - the location of the object created. Note that as this is handled in the client not the browser, no actual redirection occurs.
"Forms" for hypermedia APIs could be rendered in a "forms aware" media type like for instance Mason (https://github.com/JornWildt/Mason), Hydra (http://www.markus-lanthaler.com/hydra/) or Sirene (https://github.com/kevinswiber/siren). In Mason (which is my project) you could have a "create user" action like this:
{
"#actions": {
"create-user": {
"type": "json",
"href": "... URL to resource accepting the POST ...",
"method": "POST",
"title": "Create new user",
"schemaUrl": "... Optional URL to JSON schema definition for input ..."
"template": {
"Windows Domain": "acme"
}
}
}
}
The client can GET a resource that include the above action, find it be the name "create-user" and in this way be told which method to use, where to apply it, how the payload should be formated (in this case its JSON as described by an external schema definition) and some default values (the "template" object).
If you need more complex descriptions (like selection lists and validation rules as you mention) then you are on your own and will have to encoded that information in your own data - or use HTML or XForms.
There are multiple ways to do what you want.
You can use GET for /user/new along with a create-form link relation to get a single link. This can in plain HTML or HTML fragment, or a schema description, practically anything you want (the result will be less reusable than the other solutions).
You can use a standard MIME type which supports form descriptions. For example HAL with a form extension or collection+json.
You can use an RDF format, like JSON-LD with a proper vocab like Hydra.
I have a collection resource called Columns. A GET with Accept: application/json can't directly return a collection, so my representation needs to nest it in a property:-
{ "propertyName": [
{ "Id": "Column1", "Description": "Description 1" },
{ "Id": "Column2", "Description": "Description 2" }
]
}
Questions:
what is the best name to use for the identifier propertyName above? should it be:
d (i.e. is d an established convention or is it specific to some particular frameworks (MS WCF and MS ASP.NET AJAX ?)
results (i.e. is results an established convention or is it specific to some particular specifications (MS OData)?)
Columns (i.e. the top level property should have a clear name and it helps to disambiguate my usage of generic application/json as the Media Type)
NB I feel pretty comfortable that there should be something wrapping it, and as pointed out by #tuespetre, XML or any other representation would force you to wrap it to some degree anyway
when PUTting the content back, should the same wrapping in said property be retained [given that it's not actually necessary for security reasons and perhaps conventional JSON usage idioms might be to drop such nesting for PUT and POST given that they're not necessary to guard against scripting attacks] ?
my gut tells me it should be symmetric as for every other representation but there may be prior art for dropping the d/*results** [assuming that's the answer to part 1]*
... Or should a PUT-back (or POST) drop the need for a wrapping property and just go with:-
[
{ "Id": "Column1", "Description": "Description 1" },
{ "Id": "Column2", "Description": "Description 2" }
]
Where would any root-level metadata go if one wished to add that?
How/would a person crafting a POST Just Know that it needs to be symmetric?
EDIT: I'm specifically interested in an answer that with a reasoned rationale that specifically takes into account the impacts on client usage with JSON. For example, HAL takes care to define a binding that makes sense for both target representations.
EDIT 2: Not accepted yet, why? The answers so far don't have citations or anything that makes them stand out over me doing a search and picking something out of the top 20 hits that seem reasonable. Am I just too picky? I guess I am (or more likely I just can't ask questions properly :D). Its a bit mad that a week and 3 days even with an )admittedly measly) bonus on still only gets 123 views (from which 3 answers ain't bad)
Updated Answer
Addressing your questions (as opposed than going off on a bit of a tangent in my original answer :D), here's my opinions:
1) My main opinion on this is that I dislike d. As a client consuming the API I would find it confusing. What does it even stand for anyway? data?
The other options look good. Columns is nice because it mirrors back to the user what they requested.
If you are doing pagination, then another option might be something like page or slice as it makes it clear to the client, that they are not receiving the entire contents of the collection.
{
"offset": 0,
"limit": 100,
"page" : [
...
]
}
2) TBH, I don't think it makes that much difference which way you go for this, however if it was me, I probably wouldn't bother sending back the envelope, as I don't think there is any need (see below) and why make the request structure any more complicated than it needs to be?
I think POSTing back the envelope would be odd. POST should let you add items into the collection, so why would the client need to post the envelope to do this?
PUTing the envelope back could make sense from a RESTful standpoint as it could be seen as updating metadata associated with the collection as a whole. I think it is worth thinking about the sort of meta data you will be exposing in the envelope. All the stuff I think would fit well in this envelope (like pagination, aggregations, search facets and similar meta data) is all read only, so it doesn't make sense for the client to send this back to the server. If you find yourself with a lot of data in the envelope that the client is able to mutate - then it could be a sign to break that data out into a separate resource with the list as a sub collection. Rubbish example:
/animals
{
"farmName": "farm",
"paging": {},
"animals": [
...
]
}
Could be broken up into:
/farm/1
{
"id": 1,
"farmName": "farm"
}
and
/farm/1/animals
{
"paging": {},
"animals": [
...
]
}
Note: Even with this split, you could still return both combined as a single response using something like Facebook's or LinkedIn's field expansion syntax. E.g. http://example.com/api/farm/1?field=animals.offset(0).limit(10)
In response, to your question about how the client should know what the JSON payload they are POSTing and PUTing should look like - this should be reflected in your API documentation. I'm not sure if there is a better tool for this, but Swagger provides a spec that allows you to document what your request bodies should look like using JSON Schema - check out this page for how to define your schemas and this page for how to reference them as a parameter of type body. Unfortunately, Swagger doesn't visualise the request bodies in it's fancy web UI yet, but it's is open source, so you could always add something to do this.
Original Answer
Check out William's comment in the discussion thread on that page - he suggests a way to avoid the exploit altogether which means you can safely use a JSON array at the root of your response and then you need not worry about either of you questions.
The exploit you link to relies on your API using a Cookie to authenticate a user's session - just use a query string parameter instead and you remove the exploit. It's probably worth doing this anyway since using Cookies for authentication on an API isn't very RESTful - some of your clients may not be web browsers and may not want to deal with cookies.
Why Does this fix work?
The exploit is a form of CSRF attack which relies on the attacker being able to add a script tag on his/her own page to a sensitive resource on your API.
<script src="http://mysite.com/api/columns"></script>
The victims web browser will send all Cookies stored under mysite.com to your server and to your servers this will look like a legitimate request - you will check the session_id cookie (or whatever your server-side framework calls the cookie) and see the user is authenticated. The request will look like this:
GET http://mysite.com/api/columns
Cookie: session_id=123456789;
If you change your API you ignore Cookies and use a session_id query string parameter instead, the attacker will have no way of tricking the victims web browser into sending the session_id to your API.
A valid request will now look like this:
GET http://mysite.com/api/columns?session_id=123456789
If using a JavaScript client to make the above request, you could get the session_id from a cookie. An attacker using JavaScript from another domain will not be able to do this, as you cannot get cookies for other domains (see here).
Now we have fixed the issue and are ignoring session_id cookies, the script tag on the attackers website will still send a similar request with a GET line like this:
GET http://mysite.com/api/columns
But your server will respond with a 403 Forbidden since the GET is missing the required session_id query string parameter.
What if I'm not authenticating users for this API?
If you are not authenticating users, then your data cannot be sensitive and anyone can call the URI. CSRF should be a non-issue since with no authentication, even if you prevent CSRF attacks, an attacker could just call your API server side to get your data and use it in anyway he/she wants.
I would go for 'd' because it clearly separates the 'envelope' of your resource from its content. This would also make it easier for consumers to parse your responses, as opposed to 'guessing' the name of the wrapping property of a given resource before being able to access what it holds.
I think you're talking about two different things:
POST request should be sent in application/x-www-form-urlencoded. Your response should basically mirror a GET if you choose to include a representation of the newly created resource in your reply. (not mandatory in HTTP).
PUTs should definitely be symmetric to GETs. The purpose of a PUT request is to replace an existing resource representation with another. It just makes sense to have both requests share the same conventions, doesn't it?
Go with 'Columns' because it is semantically meaningful. It helps to think of how JSON and XML could mirror each other.
If you would PUT the collection back, you might as well use the same media type (syntax, format, what you will call it.)