I want to use a RESTful API of a web service that I have. However, I really don't know how the web service knows how to "give it" to the stand alone application since it does not have an URL. Is there a mechanism that makes URLs in this case not needed?
I think you need to read up a little more on what REST is and does. By its nature REST is a mechanism for requesting data. I.e. it is a "pull" not a "push". REST is typically used over Http - hence the need for a Url, In the same way you request/pull data everytime you visit a webpage.
If you wish to notify from one system to another as soon as change happen then you need to look at something other than REST. Alternatively your client can poll the REST service continually to check its response.
Related
I'm trying to figure out best or common practices for API design.
My concern is basically this:
PUT /users/:id
In my view this endpoint could by used for a wide array of functions.
I would use it to change the user name or profile, but what about ex, resetting a password?
From a "model" point of view, that could be flag, a property of the user, so it would "work" to send a modification.
But I would expect more something like
POST /users/:id/reset_password
But that means that almost for each modification I could create a different endpoint according to the meaning of the modification, i.e
POST /users/:id/enable
POST /users/:id/birthday
...
or even
GET /user/:id/birthday
compared to simply
GET /users/:id
So basically I don't understand when to stop using a single POST/GET and creating instead different endpoints.
It looks to me as a simple matter of choice, I just want to know if there is some standard way of doing this or some guideline. After reading and looking at example I'm still not really sure.
Disclaimer: In a lot of cases, people ask about REST when what they really want is an HTTP compliant RPC design with pretty URLs. In what follows, I'm answering about REST.
In my view this endpoint could by used for a wide array of functions. I would use it to change the user name or profile, but what about ex, resetting a password?
Sure, why not?
I don't understand when to stop using a single POST/GET and creating instead different endpoints.
A really good starting point is Jim Webber's talk Domain Driven Design for RESTful systems.
First key idea - your resources are not your domain model entities. Your REST API is really a facade in front of your domain model, which supports the illusion that you are just a website.
So your resources are analogous to documents that represent information. The URI identifies the document.
Second key idea - that URI is used by clients to cache representations of the resource, so that we don't need to send requests back to the server all the time. Instead, we have built into HTTP a bunch of standard ways for communicating caching meta data from the server to the client.
Critical to that is the rule for cache invalidation: a successful unsafe request invalidates previously cached representations of the same resource (ie, the same URI).
So the general rule is, if the client is going to do something that will modify a resource they have already cached, then we want the modification request to go to that same URI.
Your REST API is a facade to make your domain model look like a web site. So if we think about how we might build a web site to do the same thing, it can give us insights to how we arrange our resources.
So to borrow your example, we might have a web page representation of the user. If we were going to allow the client to modify that page, then we might think through a bunch of use cases (enable, change birthday, change name, reset password). For each of these supported cases, we would have a link to a task-specific form. Each of those forms would have fields allowing the client to describe the change, and a url in the form action to decide where the form gets submitted.
Since what the client is trying to achieve is to modify the profile page itself, we would have each of those forms submit back to the profile page URI, so that the client would know to invalidate the previously cached representations if the request were successful.
So your resource identifiers might look like:
/users/:id
/users/:id/forms/enable
/users/:id/forms/changeName
/users/:id/forms/changeBirthday
/users/:id/forms/resetPassword
Where each of the forms submits its information to /users/:id.
That does mean, in your implementation, you are probably going to end up with a lot of different requests routed to the same handler, and so you may need to disambiguate them there.
I have created a quite simple RESTful web service. It only supports the GET (=read) method, e.g.:
http://localhost/application/id/xyz
The corresponding information for this ID is queried from a data source and returned as JSON.
Now my question: (How) should I implement HATEOAS in this case? Does it even make sense? I understand that HATEOAS is reasonable when having a more complex structure. But in this case, there are no other resources I could link to. The client calls the web service with a certain ID and the server returns information.
Thank you!
As you've said "The client calls the web service with a certain ID" it sounds like you've written your client to visit a specific URL in your service which has the URL to visit generated by the client, i.e. your client application already knows it can visit http://localhost/application/id/xyz for the xyz ID.
If you'd like to leverage some of the power of HATEOAS and decouple yourself from this (slight) dependency, you could instead be querying http://localhost/application/id?query=xyz which could return a list of valid links (if any exist). That way you could change the format or structure of the linked URL without issues for your client (of course, you'd still be dependent on the query URL in some way).
However, as your usage is so simple, this sounds like overkill and unnecessary work so I'd suggest you don't need to worry about HATEOAS until you have a more complex system or clients :)
In HATEOS your return value is not an ID but a URL. Invoking that URL links you to the next resource in the web. Just like a web page containing links to other web pages.
Currently as it stands, if a user reads the source of my web application, they'd be able to determine the direct URIs of all the RESTful services my web application utilizes.
The problem I see is this: My web application knows how to correctly use the API, and I might not have thought of every single validation known to man to prevent bad data from being sent through the API.
And so with that is there a method to prevent "direct" access to the API and limit it only to my web application?
P.S. As an FYI: API calls concerning a user are protected by the presence of a user-specific cookie which is only issued upon login. This means I'm not too afraid of User X being able to directly modify User Y's data through the API.
No.
If the browser is making the request, the user can spoof the request. Period.
My web application knows how to correctly use the API
That's good, but that's leading you down the path of assuming client-side functionality executed as intended. Never make that assumption.
I might not have thought of every single validation known to man to prevent bad data from being sent through the API
This statement leads me to believe that the API itself is more complex than it needs to be. The best thing you can do is simplify. It's difficult to be more specific without seeing specific code, but API requests should be fairly simple and straightforward and the same techniques to prevent malicious code from getting through should be applied universally. The same general rules apply here as in any web application interaction...
Never trust anything that came from the client
Never assume client-side code executed as intended
Never execute input as code, always treat it as a raw value
and so on...
As you mention toward the end, you've already taken care of authentication and authorization for the requests. Given that, if User X is permitted to make a given API call, then what you're essentially asking is, "How do I allow User X to make an API call without allowing User X to make an API call?" The server can't tell the difference. A request is a request.
Sure, there are things you can try, such as always including some custom header in requests made from code. But anybody can inspect that request and spoof that header. The user's browser isn't part of your application and isn't under your control.
quick question - I was reading about RESTful services yesterday and someone had asked why SOAP wasn't RESTful. The answer was that SOAP doesn't have the 'generality of interfaces' property as is required by REST.
Then it struck me that I had been adding custom routes to my Web API like so:
Custom Routing with ASP.NET Web API
By doing that - I made my web API non-generic, thereby making the service non-RESTful, right? Not that that's a big deal, I just want to know whether I grasped the concepts correctly.
Well the rest rqeuires you to identify resoruces alone, not actions on them.
For example you might have an action addComment on Person, your route being
POST persons/2/addComment
This would make it non restful. The ideal way to do this would be:
POST persons/2/comments
For deleting a comment DELETE persons/2/comments/{commebntid}
So if you vary from this, your service becomes non restful. Its pretty hard to make a completely restful interface.
For example, if you have an object account, that you directly increment or decrement balance
accounts/2. You might have withdraw and deposit actions. POST accoints/2/withdraw. In rest, you need to either pass the balance as a parameter after decrementing it (PUT). There may be cases where you donot want to do this. You might not want to let the world know the balance of the user. Then you cant easily use put. You'd have to create a new entity: transaction and create transactions and calculate the account balance on the basis of transactions.
Ther eis no such thing as a generic API. You can't use amazons api and facebooks api interchangibly since the entities and operations are different. Don't worry too much about generalization. Just understand what the RESTful way is, and see if you can implemen it. If you have to tweak around it a bit, that's fine
in SAML 2.0 you can use the AttributeStatement element to provide any kind of application specific information.
What I was wondering, is it really good design to pass business related information within a SAML assertion? Shouldn't this data be provided in a e.g. separate web services call?
I just want to ask for best practice in this case or any real world experiences.
Regards,
Andreas
It depends a lot on just what information you're conveying. For instance, on the application I work on, we use attributes to indicate what web site features should be shown to the user being logged on. That's clearly an appropriate use. Now, we also allow use of attributes to create a user profile, even though we have a web service that does the same thing (and in fact, the implementation calls the web service behind the scenes). It's not an ideal context for that sort of thing; there's no endpoint to convey the web service response to, or any errors resulting from the attempt. But we get a fair amount of resistance from customers, who don't want to have to call a separate web service before they can make an SSO call. So we've had to compromise. What we've done is require that if a customer wants to use this particular functionality, that they provide an endpoint (either email address or web page) to receive errors from the web service call. And if they're concerned about security of the information being conveyed, they can use standard XML encryption.