Ok, so I'm working on some health related app.
So far, we have our custom database, with Rest API end points, java spring app and oracle database.
Now they are considering to move to the HL7/FHIR specifications. I know pretty much nothing about this framework.
One of our requirements is some sort of audit module recording all sorts of events such as "this patient file got modified by that doctor".
The thing is the framework seems to include an AuditEvent module.
https://www.hl7.org/fhir/auditevent.html
Ideally when a PUT rest call occurs on a "patient" resource, we would create and save a new AuditEvent resource.
The problem I face is how do I know the author of the PUT? The staff member that triggered the patient record update?
There is nothing in their REST recommendations that specifies how we are supposed to cover that aspect? The "author" of a PUT.
https://www.hl7.org/fhir/http.html#vread
Is it specific to how we implement the specifications, some sort of session/security related userID
Many Thanks
PS: there would be other types of events apart from just recording REST calls.
The typical mechanism for identifying users in FHIR is OAuth. There's a bit of discussion on this in the specification here: http://www.hl7.org/fhir/security.html
It makes reference to the Smart on FHIR work which gives some additional guidance.
As well, you may want to look at the Heart work: http://openid.net/wg/heart
The high-level gist is that the authentication happens at the HTTP layer via redirects which then results in a token that gets included in the HTTP header for the PUT and other RESTful operations.
I have been trying to understand what a RESTful API/Web Application is supposed to look like and I cant help but wonder if the Web is already built under a RESTful architecture. Every website is basically a collection of web pages (A specific representation of the state of the Web App) and you change states by clicking links. Therefore you have Representational State Transfer!
Am I wrong in thinking this? Also, every SO answer to the question 'What is REST?' which I have managed to find fails to provide an example and show the difference between a non-RESTful API and a RESTful API.
Can someone provide that please? It would help in clearing things up. I do not want abstract terms in the answer because it would be more helpful to fit the abstract answer into an example rather than try to figure out an example from an abstract answer. Beginner speaking :)
Deepak,
in a nutshell, REST in an architectural style which helps your application make the most of the Web. The term was coined in the thesis by Roy Fielding called Architectural Styles and the Design of Network-based Software Architectures.
While a lot of REST services use HTTP and JSON, they are not limited to the aforementioned protocol and format. To tell whether a service is RESTful or not, one can use the so-called Richardson Maturity Model. The services that are not at the level three of the model are sometimes called RESTlike.
First of all, REST services are stateless, that is if you receive a huge list from the server, which is paginated, such as a list of books from the Amazon, the page you are on isn't stored at the server side, it is the responsibility of the client to inform the server about the next page's number. Also URIs are used to identify resources, e.g. each book's description can be retrieved using its unique URI, and HTTP methods such as GET and POST are used to work with resources, for instance, the former can be used to retrieve the book info and the latter to add a new book.
The crux of the style is a concept called Hypermedia As The Engine Of An Application state(HATEOAS). A simplistic explanation of what it is could be that the representations of resources (book info can be in JSON, XML, HTML etc.) should use hyperlinks to make those representations self-describing, e.g. if the book info can be edited, the link to do so should be added.
There are various proposals how to add hypermedia to representations. One possible format is Hypertext Application Language (HAL). Others include but not limited to JSON API, JSON-LD, UBER.
Personally I ventured to elaborate on the topic in my blog:
What is REST?
REST: Uniform interface
Introduction to Hypertext Application Language (HAL)
Regards, Dmitry
One of the goals of the REST API architecture is decoupling of the client and the server.
One of the questions I have run across in planning a REST API is: "how does the client know what is a valid payload for POST methods?"
Somehow the API needs to communicate to the UI what a valid payload for a given resource’s POST method. Otherwise here we are back at depending on out-of-band knowledge being necessary to work with an API and we are tightly coupled again.
So I’ve had this idea that the API response for a GET on a resource would provide a specification for constructing a valid payload for the POST method on that resource. This would include field names, data type, max length, etc.
This guy has a similar idea.
What's the correct way to handle this? Are most people just relying on out-of-band information? What are people doing in the real world with this problem?
EDIT
Something I have come up with to solve this problem is illustrated in the following sequence diagram:
The client and the api service are separate. The client knows:
Entry point
How to navigate the API via the hypermedia.
Here's what happens:
Someone (user) requests the registration page from the client
The client requests the entry point from the API and receives all hypermedia links with appropriate meta data on how to traverse them legally.
Client constructs the registration form based on the meta data associated with the registration hypermedia POST method.
User fills in the form and submits.
Client POSTs to the API with the correct data and all is well.
No magic /meta resouces, no need to use a method for the meta data. Everything is provided by the API.
Thoughts?
Most people are relying on out-of-band information. This is usually ok, though, because most clients aren't being built dynamically, but statically. They rely on known parts of the API rather than being HATEOAS-driven.
If you are developing or want to support a metadata-driven client, then yes, you're going to need to come up with a schema for providing that information. The implementation you linked to seems reasonable after a quick skim. Note that you've only moved the problem, though. Clients still need to know how to interpret the information in the metadata responses.
Your are right, the client should understand the semantics of the links in the response, and choose the right one from them to achieve its goal. The client is coupled to the semantics the API provides about this and not to the API itself. So for example a client should not retrieve information from the URI structure, since it is tightly coupled to the actual API.
I know of 2 current solution types about this:
by HAL+JSON you use IANA link relations to describe what the link does, and vendor specific MIME types to describe the schema of the fields
by JSON-LD (or any other RDF format) with Hydra vocab you send back RDF metadata according to the operation the link calls. This meta-data can contain the validation details of the fields (xsd vocab) and the semantics of the fields (microdata, microformats, etc...). This information is completely decoupled from the API implementation, so it might be a better option than using vendor specific MIME types, but Hydra is still under development and HAL is much simpler.
However your solution is valid as well, I think you should check both of these, since they are already standard solutions, and the uniform interface / self-descripting message constraint of REST encourages the usage of existing standards instead of custom solutions. But it is up to you if you want to create an own standard.
I think you are asking about, Rest API meta data handling. Unlike SOAP, Rest APIs doesn't use meta data normally, but sometimes it can be pretty useful, once your api size gets bigger.
I think you should look into swagger. It is the most elegant you can find out for rest apis. I have being using it for sometime and with the annotation support it is being rather easy to work with. It also has many examples found on github. Other advantage is, it contains nice configurable ui.
Apart from that you can find other ways of doing it like WADL and WSDL 2.0. Even-though I haven't being using them, you can read more about them here.
With RFC 6861, you can link to your form with create-form and edit-form Link Relations, instead of the client constructing the form by itself. The corresponding form should have the necessary schema to construct the POST request.
How do you document a REST API? Not just the documentation of what the resources are, but really what is the data that gets sent in the request and what the data is that gets sent back in the response. It is not useful enough to know that something expects XML to be sent and returns XML; or JASN; or whatever. How do you document the data that gets sent in the request and the data sent back in the response?
Best I could find so far is the Enunciate tool where you can document your REST API and the data elements. Is Enunciate the right type of tool for this and am I missing out on any other tools that offer this that I should look at?
Consumers of my REST API can be in any language python, Java, .NET, etc
The approach that I've decided on for my project is Enunciate. Seems to be the de facto standard for REST API documentation.
I've experience using Enunciate which is great but I don't really like the clients that you can generate with it.
On the other hand, I've been using swagger on my last projects and it seems to fit my needs, it's really cool you should give a try!
UPDATE 03/08/2016: Looks like you can use Enunciate to build swagger docs.
See this.
I may be wrong, but it seems like you want something similar to a WSDL and XML Schema to document your API. I suggest reading Joe Gregorio's post on Do we need WADL? It has a good discussion on why not to use this approach for a REST API. If you don't want to read the entire article, the basic idea is that API-like documentation (i.e. WADL) will never be sufficient and will lead to brittle interfaces. Another good article is Does REST need a description language? It has a lot of good links to this type of discussion.
While his post gives you advice on what not to do, it doesn't really answer the question on what you should do. The big thing about REST is the idea of a uniform interface. In other words, GET, PUT, POST, and DELETE should do exactly what you think they should do. GET retrieves a representation of the resource, PUT updates, POST creates, and DELETE deletes.
The big question is then about describing your data and what it means. You can always go the route of defining an XML Schema or something similar and generate documentation from the schema. Personally, I don't find machine generated documentation all that useful.
In my humble opinion, the best data formats have extensive, human readable documentation with examples. This is the only way I know how to properly describe semantics. I like the use of Sphinx to generate this type of documentation.
I am not sure if you are asking for a tool to assist you in this, or if you're asking what the best practice is (or both).
As far as best practices, the same things apply to REST documentation as other software documentation - provide a good landing page with breadth (ie, a list of your resources logically organized with a blurb about what they do and their URI) with drill-down pages that explain in depth what each one does, with examples. Twitter's REST API is very well documented and it should be a good model.
Twitter API main page
Sample drilldown of one resource
I really love that drilldown page. It lists all of the parameters you need, with a description of each one. It has a sidebar that lists the supported types. It has links to related pages and other pages with the same tag. It has a sample request and response.
Apparently, REST is just a set of conventions about how to use HTTP. I wonder which advantage these conventions provide. Does anyone know?
I don't think you will get a good answer to this, partly because nobody really agrees on what REST is. The wikipedia page is heavy on buzzwords and light on explanation. The discussion page is worth a skim just to see how much people disagree on this. As far as I can tell however, REST means this:
Instead of having randomly named setter and getter URLs and using GET for all the getters and POST for all the setters, we try to have the URLs identify resources, and then use the HTTP actions GET, POST, PUT and DELETE to do stuff to them. So instead of
GET /get_article?id=1
POST /delete_article id=1
You would do
GET /articles/1/
DELETE /articles/1/
And then POST and PUT correspond to "create" and "update" operations (but nobody agrees which way round).
I think the caching arguments are wrong, because query strings are generally cached, and besides you don't really need to use them. For example django makes something like this very easy, and I wouldn't say it was REST:
GET /get_article/1/
POST /delete_article/ id=1
Or even just include the verb in the URL:
GET /read/article/1/
POST /delete/article/1/
POST /update/article/1/
POST /create/article/
In that case GET means something without side-effects, and POST means something that changes data on the server. I think this is perhaps a bit clearer and easier, especially as you can avoid the whole PUT-vs-POST thing. Plus you can add more verbs if you want to, so you aren't artificially bound to what HTTP offers. For example:
POST /hide/article/1/
POST /show/article/1/
(Or whatever, it's hard to think of examples until they happen!)
So in conclusion, there are only two advantages I can see:
Your web API may be cleaner and easier to understand / discover.
When synchronising data with a website, it is probably easier to use REST because you can just say synchronize("/articles/1/") or whatever. This depends heavily on your code.
However I think there are some pretty big disadvantages:
Not all actions easily map to CRUD (create, read/retrieve, update, delete). You may not even be dealing with object type resources.
It's extra effort for dubious benefits.
Confusion as to which way round PUT and POST are. In English they mean similar things ("I'm going to put/post a notice on the wall.").
So in conclusion I would say: unless you really want to go to the extra effort, or if your service maps really well to CRUD operations, save REST for the second version of your API.
I just came across another problem with REST: It's not easy to do more than one thing in one request or specify which parts of a compound object you want to get. This is especially important on mobile where round-trip-time can be significant and connections are unreliable. For example, suppose you are getting posts on a facebook timeline. The "pure" REST way would be something like
GET /timeline_posts // Returns a list of post IDs.
GET /timeline_posts/1/ // Returns a list of message IDs in the post.
GET /timeline_posts/2/
GET /timeline_posts/3/
GET /message/10/
GET /message/11/
....
Which is kind of ridiculous. Facebook's API is pretty great IMO, so let's see what they do:
By default, most object properties are returned when you make a query.
You can choose the fields (or connections) you want returned with the
"fields" query parameter. For example, this URL will only return the
id, name, and picture of Ben:
https://graph.facebook.com/bgolub?fields=id,name,picture
I have no idea how you'd do something like that with REST, and if you did whether it would still count as REST. I would certainly ignore anyone who tries to tell you that you shouldn't do that though (especially if the reason is "because it isn't REST")!
Simply put, REST means using HTTP the way it's meant to be.
Have a look at Roy Fielding's dissertation about REST. I think that every person that is doing web development should read it.
As a note, Roy Fielding is one of the key drivers behind the HTTP protocol, as well.
To name some of the advandages:
Simple.
You can make good use of HTTP cache and proxy server to help you handle high load.
It helps you organize even a very complex application into simple resources.
It makes it easy for new clients to use your application, even if you haven't designed it specifically for them (probably, because they weren't around when you created your app).
Simply put: NONE.
Feel free to downvote, but I still think there are no real benefits over non-REST HTTP. All current answers are invalid. Arguments from the currently most voted answer:
Simple.
You can make good use of HTTP cache and proxy server to help you handle high load.
It helps you organize even a very complex application into simple resources.
It makes it easy for new clients to use your application, even if you haven't designed it specifically for them (probably, because they weren't around when you created your app).
1. Simple
With REST you need additional communication layer for your server-side and client-side scripts => it's actually more complicated than use of non-REST HTTP.
2. Caching
Caching can be controlled by HTTP headers sent by server. REST does not add any features missing in non-REST.
3. Organization
REST does not help you organize things. It forces you to use API supported by server-side library you are using. You can organize your application the same way (or better) when you are using non-REST approach. E.g. see Model-View-Controller or MVC routing.
4. Easy to use/implement
Not true at all. It all depends on how well you organize and document your application. REST will not magically make your application better.
IMHO the biggest advantage that REST enables is that of reducing client/server coupling. It is much easier to evolve a REST interface over time without breaking existing clients.
Discoverability
Each resource has references to other resources, either in hierarchy or links, so it's easy to browse around. This is an advantage to the human developing the client, saving he/she from constantly consulting the docs, and offering suggestions. It also means the server can change resource names unilaterally (as long as the client software doesn't hardcode the URLs).
Compatibility with other tools
You can CURL your way into any part of the API or use the web browser to navigate resources. Makes debugging and testing integration much easier.
Standardized Verb Names
Allows you to specify actions without having to hunt the correct wording. Imagine if OOP getters and setters weren't standardized, and some people used retrieve and define instead. You would have to memorize the correct verb for each individual access point. Knowing there's only a handful of verbs available counters that problem.
Standardized Status
If you GET a resource that doesn't exist, you can be sure to get a 404 error in a RESTful API. Contrast it with a non-RESTful API, which may return {error: "Not found"} wrapped in God knows how many layers. If you need the extra space to write a message to the developer on the other side, you can always use the body of the response.
Example
Imagine two APIs with the same functionality, one following REST and the other not. Now imagine the following clients for those APIs:
RESTful:
GET /products/1052/reviews
POST /products/1052/reviews "5 stars"
DELETE /products/1052/reviews/10
GET /products/1052/reviews/10
HTTP:
GET /reviews?product_id=1052
POST /post_review?product_id=1052 "5 stars"
POST /remove_review?product_id=1052&review_id=10
GET /reviews?product_id=1052&review=10
Now think of the following questions:
If the first call of each client worked, how sure can you be the rest will work too?
There was a major update to the API that may or may not have changed those access points. How much of the docs will you have to re-read?
Can you predict the return of the last query?
You have to edit the review posted (before deleting it). Can you do so without checking the docs?
I recommend taking a look at Ryan Tomayko's How I Explained REST to My Wife
Third party edit
Excerpt from the waybackmaschine link:
How about an example. You’re a teacher and want to manage students:
what classes they’re in,
what grades they’re getting,
emergency contacts,
information about the books you teach out of, etc.
If the systems are web-based, then there’s probably a URL for each of the nouns involved here: student, teacher, class, book, room, etc. ... If there were a machine readable representation for each URL, then it would be trivial to latch new tools onto the system because all of that information would be consumable in a standard way. ... you could build a country-wide system that was able to talk to each of the individual school systems to collect testing scores.
Each of the systems would get information from each other using a simple HTTP GET. If one system needs to add something to another system, it would use an HTTP POST. If a system wants to update something in another system, it uses an HTTP PUT. The only thing left to figure out is what the data should look like.
I would suggest everybody, who is looking for an answer to this question, go through this "slideshow".
I couldn't understand what REST is and why it is so cool, its pros and cons, differences from SOAP - but this slideshow was so brilliant and easy to understand, so it is much more clear to me now, than before.
Caching.
There are other more in depth benefits of REST which revolve around evolve-ability via loose coupling and hypertext, but caching mechanisms are the main reason you should care about RESTful HTTP.
It's written down in the Fielding dissertation. But if you don't want to read a lot:
increased scalability (due to stateless, cache and layered system constraints)
decoupled client and server (due to stateless and uniform interface constraints)
reusable clients (client can use general REST browsers and RDF semantics to decide which link to follow and how to display the results)
non breaking clients (clients break only by application specific semantics changes, because they use the semantics instead of some API specific knowledge)
Give every “resource” an ID
Link things together
Use standard methods
Resources with multiple representations
Communicate statelessly
It is possible to do everything just with POST and GET? Yes, is it the best approach? No, why? because we have standards methods. If you think again, it would be possible to do everything using just GET.. so why should we even bother do use POST? Because of the standards!
For example, today thinking about a MVC model, you can limit your application to respond just to specific kinds of verbs like POST, GET, PUT and DELETE. Even if under the hood everything is emulated to POST and GET, don't make sense to have different verbs for different actions?
Discovery is far easier in REST. We have WADL documents (similar to WSDL in traditional webservices) that will help you to advertise your service to the world. You can use UDDI discoveries as well. With traditional HTTP POST and GET people may not know your message request and response schemas to call you.
One advantage is that, we can non-sequentially process XML documents and unmarshal XML data from different sources like InputStream object, a URL, a DOM node...
#Timmmm, about your edit :
GET /timeline_posts // could return the N first posts, with links to fetch the next/previous N posts
This would dramatically reduce the number of calls
And nothing prevents you from designing a server that accepts HTTP parameters to denote the field values your clients may want...
But this is a detail.
Much more important is the fact that you did not mention huge advantages of the REST architectural style (much better scalability, due to server statelessness; much better availability, due to server statelessness also; much better use of the standard services, such as caching for instance, when using a REST architectural style; much lower coupling between client and server, due to the use of a uniform interface; etc. etc.)
As for your remark
"Not all actions easily map to CRUD (create, read/retrieve, update,
delete)."
: an RDBMS uses a CRUD approach, too (SELECT/INSERT/DELETE/UPDATE), and there is always a way to represent and act upon a data model.
Regarding your sentence
"You may not even be dealing with object type resources"
: a RESTful design is, by essence, a simple design - but this does NOT mean that designing it is simple. Do you see the difference ? You'll have to think a lot about the concepts your application will represent and handle, what must be done by it, if you prefer, in order to represent this by means of resources. But if you do so, you will end up with a more simple and efficient design.
Query-strings can be ignored by search engines.