I have studied various resources for URI design best practices. Almost every author or blogger says RESTFul API URI have to look like this for example.
/* List all users in account 2 where user id is 1 */
`/users/1/accounts/2/users` [GET]
Above api caller have to pass above two ids in every request.
But my scenario is quite different.
There is a Resource Manager(RM) before my API server so every request have to pass through RM for authentication with valid token to access above example API. Note: [token send via header]
Once request is authorized in return RM provide user info i.e.(user_id, account_id etc.) to my API server via interceptor.
Question is my API server is already aware of user_id and his account_id then still there is need to get these information in API URI.
I have tried following design:
1. /users/accounts/users
2. /accounts/users
3. /users
What is best suitable design for this scenario? I spent two weeks but couldn't decide because these are enterprise APIs design; once designed than will never changed.
You should include ids in the URI for the very reason you give at the end - your API will be very difficult, maybe impossible, to change once it's being used. On the other hand, your implementation will change over time. Your authentication / authorization mechanism could change. Your enterprise may wish to move to an model which doesn't pass around ids in this fashion, and they certainly won't want to find that they have to re-design every single API which depends on the old behaviour.
At the end of the day, including enough information in the URI for the URI to identify the resource it relates to is a key part of ReST. The URI should be all that you need to identify the resource, you don't depend on out-of-band information or implementation details to further identify the resource you're addressing.
Related
I want to create a microservice for "orders". The service will have typical actions like "get orders" or "create an order".
I would like to expose this service in two ways:
User frontend: If you call /orders, you will see your orders
Support frontend: if you call /orders, you will see all the orders of all the users
I would like to deploy one API (orders) that can be called from 2 API gateways (user and support). But, I don't know how to do it without duplicating code.
Is this the right approach?
I'm using AWS Apigateway + Lambda + Serverless.
In some way you're being able to differentiate the user that is making the request inside your lambda function, because you need to get only its orders. Based on that I'm considering that you're receiving some kind of token in your lambda where you can extract the correct user.
Considering that scenario, one standard solution to your problem is add something to your token that differentiate if the user is from the support group or not. Normally you add a claim to the token informing that he/she is part of the support group. Then inside your lambda you check this token and give a different answer based on your requirements. But for that solution, you'll need to have means to add new claims/manage your identity provider data (user information inside your service that provides user tokens).
But with that solution you will find a small problem: if a support user must get all the orders and in another moment only its orders you won't find an easy way to implement this. If your requirements demand that you provide both use cases for support users you will need another solution.
In that case another solution would be to provide two different endpoints (API Gateway API's) touching the same backend lambda. In the normal endpoint you forward the request to the backend and the lambda gets all the orders for the user. In the support endpoint you add something else to the request (can be a query parameter or a http header).
For a more secure solution, your support endpoint must not allow requests from people outside the support group. And if you go for a query parameter alternative, you must block this exact query param in the normal endpoint. Someone can abuse the normal api sending the query param for it and get all the orders if you just forward the query params downstream.
You will do all this different configuration in the integration request of AWS API Gateway. You can find how it works here.
I'm working on API that tries to stay in RESTful principles, although one requirement keeps bugging me.
We use JWT based authentication. Inside JWT claims we store roles of the user. Now our main GET endpoint (let's call it ListAllOffers for simplicity) behaves differently depending on what role the user have:
if API recognizes admin via JWT it responds with full list of Offers
if API recognizes ordinary user via JWT it responds with narrowed list of Offers (depending on relation in DB)
My concerns is: is it ok according to REST principles or any unwritten REST practices? I am used to modify response object according to argument from url, params from querystring or alternatively via header values. Altering JSON response basing JWT seems not explicit enough that is feels some kinda strange.
Bonus question: is it against any of REST principles how should this requirement be implemented.
You'll find lots of APIs have resources where the value changes depending on the authenticated user (see GitHub's API).
When it comes to REST the endpoint must always reference the same resource. However, you may choose to represent that resource in any way you wish. Masking some of the offers because the user is not an admin has not changed the resource only the representation you are giving to that user.
While the REST specification doesn't have any specific examples of changing representations due to authorisation it is still a worthwhile read.
If you are concerned about changing the representation implicitly there are a few options available that would make it more explicit whilst still following RESTful standards.
You could add a query parameter that explicitly requests only the current user's offers: /offers?show=mine.
If the offers are 'owner' by a user you could also do something like: /users/{username}/offers. Here a user would be authorised only for their own offers. An admin would of course be authorised for any.
Overall the key point is this: an endpoint must always represent the same resource but how it represents it is up to you.
Here is my little API with two URL :
/api/location/list -> GET
/api/location/detail -> GET
I'm looking for a process to secure this service with authentication. For now, it can be accessed by only one user (me).
I think oAuth is too complex in my case and I found this resource for designing a simple API.
I understand the principle of private/public key and HMAC but I have a big concern about this :
Say my webservice is consumed by an ajax request with GET verb. I have something like /api/location/list?apikkey=userid&hash=abcde.
A end user can easily sniffed the network during the request (via a simple chrome console), capture full url and access directly to the service multiple times (I think it's a case of replay attacks).
Differents resources talk about timestamp or nonce to make a request unique but I'm a bit lost with implementation.
Any ideas ?
You can try JWToken auth specs, simpler than Oauth, but avoid authorization data as url parameter if possible and use Header's request instead.
If needed consider also ssl encryption at tcp level.
Perhaps you could try to use a token-based approach for security, as described in this blog post:
Implementing authentication with tokens for RESTful applications - https://templth.wordpress.com/2015/01/05/implementing-authentication-with-tokens-for-restful-applications/
The idea is to authenticate to an authentication resource (that can be part of your application) to get temporary token that can be refreshed with a refresh token when expired.
With the use of HTTPS, it seems to be appropriate.
I think that it depends on the security level you expect. Signature-based authentication (the AWS approach) is great but is a bit complex to implement by hand.
Hope it helps you,
Thierry
When designing REST API is it common to authenticate a user first?
The typical use case I am looking for is:
User wants to get data. Sure cool we like to share! Get a public API key and read away!
User wants to store/update data... woah wait up! who are you, can you do this?
I would like to build it once and allow say a web-app, an android application or an iPhone application to use it.
A REST API appears to be a logical choice with requirements like this
To illustrate my question I'll use a simple example.
I have an item in a database, which has a rating attribute (integer 1 to 5).
If I understand REST correctly I would implement a GET request using the language of my choice that returns csv, xml or json like this:
http://example.com/product/getrating/{id}/
Say we pick JSON we return:
{
"id": "1",
"name": "widget1",
"attributes": { "rating": {"type":"int", "value":4} }
}
This is fine for public facing APIs. I get that part.
Where I have tons of question is how do I combine this with a security model? I'm used to web-app security where I have a session state identifying my user at all time so I can control what they can do no matter what they decide to send me. As I understand it this isn't RESTful so would be a bad solution in this case.
I'll try to use another example using the same item/rating.
If user "JOE" wants to add a rating to an item
This could be done using:
http://example.com/product/addrating/{id}/{givenRating}/
At this point I want to store the data saying that "JOE" gave product {id} a rating of {givenRating}.
Question: How do I know the request came from "JOE" and not "BOB".
Furthermore, what if it was for more sensible data like a user's phone number?
What I've got so far is:
1) Use the built-in feature of HTTP to authenticate at every request, either plain HTTP or HTTPS.
This means that every request now take the form of:
https://joe:joepassword#example.com/product/addrating/{id}/{givenRating}/
2) Use an approach like Amazon's S3 with private and public key: http://www.thebuzzmedia.com/designing-a-secure-rest-api-without-oauth-authentication/
3) Use a cookie anyway and break the stateless part of REST.
The second approach appears better to me, but I am left wondering do I really have to re-invent this whole thing? Hashing, storing, generating the keys, etc all by myself?
This sounds a lot like using session in a typical web application and rewriting the entire stack yourself, which usually to me mean "You're doing it wrong" especially when dealing with security.
EDIT: I guess I should have mentioned OAuth as well.
Edit 5 years later
Use OAuth2!
Previous version
No, there is absolutely no need to use a cookie. It's not half as secure as HTTP Digest, OAuth or Amazon's AWS (which is not hard to copy).
The way you should look at a cookie is that it's an authentication token as much as Basic/Digest/OAuth/whichever would be, but less appropriate.
However, I don't feel using a cookie goes against RESTful principles per se, as long as the contents of the session cookie does not influence the contents of the resource you're returning from the server.
Cookies are evil, stop using them.
Don't worry about being "RESTful", worry about security. Here's how I do it:
Step 1: User hits authentication service with credentials.
Step 2: If credentials check out, return a fingerprint, session id, etc..., and pop them into shared memory for quick retrieval later or use a database if you don't mind adding a few milliseconds to your web service turnaround time.
Step 3: Add an entry point call to the top of every web service script that validates the fingerprint and session id for every web service request.
Step 4: If the fingerprint and session id aren't valid or have timed out redirect to authentication.
READ THIS:
RESTful Authentication
Edit 3 years later
I completely agree with Evert, use OAuth2 with HTTPS, and don't reinvent the wheel! :-)
By simpler REST APIs - not meant for 3rd party clients - JSON Web Tokens can be good as well.
Previous version
Use a cookie anyway and break the stateless part of REST.
Don't use sessions, with sessions your REST service won't be well scalable... There are 2 states here: application state (or client state or session s) and resource state. Application state contains the session data and it is maintained by the REST client. Resource state contains the resource properties and relations and is maintained by the REST service. You can decide very easy whether a particular variable is part of the application state or the resource state. If the amount of data increases with the number of active sessions, then it belongs to the application state. So for example user identity by the current session belongs to the application state, but the list of the users or user permissions belongs to the resource state.
So the REST client should store the identification factors and send them with every request. Don't confuse the REST client with the HTTP client. They are not the same. REST client can be on the server side too if it uses curl, or it can create for example a server side http only cookie which it can share with the REST service via CORS. The only thing what matters that the REST service has to authenticate by every request, so you have to send the credentials (username, password) with every request.
If you write a client side REST client, then this can be done with SSL + HTTP auth. In that case you can create a credentials -> (identity, permissions) cache on the server to make authentication faster. Be aware of that if you clear that cache, and the users send the same request, they will get the same response, just it will take a bit longer. You can compare this with sessions: if you clear the session store, then users will get a status: 401 unauthorized response...
If you write a server side REST client and you send identification factors to the REST service via curl, then you have 2 choices. You can use http auth as well, or you can use a session manager in your REST client but not in the REST service.
If somebody untrusted writes your REST client, then you have to write an application to authenticate the users and to give them the availability to decide whether they want to grant permissions to different clients or not. Oauth is an already existing solution for that. Oauth1 is more secure, oauth2 is less secure but simpler, and I guess there are several other solution for this problem... You don't have to reinvent this. There are complete authentication and authorization solutions using oauth, for example: the wso identity server.
Cookies are not necessarily bad. You can use them in a RESTful way until they hold client state and the service holds resource state only. For example you can store the cart or the preferred pagination settings in cookies...
Some existing web services I consume have methods that look something like this:
List<Employee> employees =
employeeService.GetEmployees(accessKey, allDepartments);
The accessKey serves two purposes; it acts as both authentication and identification. Only valid access codes are responded to (authentication) and it services as a link to a particular client's data.
If the services were to be done a restful manner I'm not sure how this would be achieved. I definitely would not want to do something like this:
http://www.business.com/<GuidHere>/Employees/
Since this would show the accessKey, which is somewhat secret, (ie, its usually in an encrypted file on the client which uses this) we can't show the GUID in a URI. How is something like this achieved using a restful architecture?
You could send the authentication token using HTTP headers.
If this is a RESTful web service I'm assuming it's being consumed by a machine so why not pass the access key in the url?
At then end of the day you need to put it somewhere and hiding them in hidden form fields in the browser (if the service is to be browsable) isn't much in the way of security.
If the key is so sensitive, why not symmetrically encrypt on the server per session and pass that value around instead?
Just some thoughts.
Kev
If time isn't an issue implementing OAuth security may be useful. OAuth uses a public key, and also a secret. The mess is hashed (in most cases) and the server will use the public key + it's copy of the secret to do the same hashing and make sure its result matches the requests.
The benefit is you wouldn't need to use HTTPS or POST. Get* REST api methods should be using the HTTP GET method (I'm not sure if being RESTful is your goal, just thought I would point that out). I agree with Mr. Pang, use http://www.business.com/employees. The query string could contain the list of department ids.
For your case the service call wouldn't have the 'accessKey' argument, rather it would become the public key (I imagine) and be used in either the headers, query string, or as a POST param.
Some good info on OAuth: http://www.hueniverse.com/hueniverse/
As Troy Alford pointed out, my original suggestion was incorrect. You shouldn't be using POST in a situation like this. You should use a GET request with the authentication information in the HTTP headers. Take a look at basic access authentication for one way to do that.