Is there a way to document http error codes using spring-restdocs? I did not find anything about the same on http://docs.spring.io/spring-restdocs/docs/current/reference/html5/
Any help with an example will be greatly appreciated.
Regards,
Surya
Spring REST Docs doesn't provide anything to help you document HTTP error codes. The theory is that it isn't really necessary to document error codes, and certainly not on every single resource in the API.
The HTTP spec provides definitions for its error codes and your API should adhere to the definitions. This allows users of the API to use their existing knowledge of HTTP, rather than having to learn something new that's specific to your API. If you aren't sure that your users will already have this knowledge, you could include some information about HTTP error codes in an overview section of the documentation. This is the approach taken in one of Spring REST Docs' sample projects. Both the Asciidoctor source and resulting HTML documentation are available online .
Related
I'm trying to use the Swagger UI, and it says that I should begin by writing an api-doc that describes the exact api for a REST api. The problem is that I have no idea what this means. Is this document written in plain English? Or is there a certain format that will be able to generate the UI?
Thank you!
Swagger is a specification for describing REST APIs. Documentation of the specification can be found here - https://github.com/swagger-api/swagger-spec.
Generally, there are two ways to document your API. If you already have an existing API with code, you can use any of the existing libraries (https://github.com/swagger-api/swagger-spec#additional-libraries) to integrate into your code and generate documentation at run time. Some of those libraries also offer offline generation of such docs.
If you're looking to design an API, or would rather not integrate another library into your application, you can use https://github.com/swagger-api/swagger-editor either locally or with the online version - http://editor.swagger.io.
Once you have the documentation, you can use Swagger UI to visualize and test it.
I am trying to create a RESTful web service that accepts JSON arguments and gives out a JSON response.
What I want is to accept HTTP requests made to my URL endpoint.
Something like,
POST /the/endpoint HTTP/1.1
Host: mywebsite.com
{"name":"yourname", "department":"your_department"}
Do a DB read at the backend and give relevant parameters like, say Manager name, salary etc as a JSON object, as the response.
What's the best way to go about it? I was thinking of using Java servlets for this? Is there a better way?
PS - I am just getting started so detailed answers or links to tutorials as to how to implement it would be much appreciated.
Thanks.
Yes you can easily do this with Servlets and some Json Libs for Marshalling /unmarshalling the Json Object to Java Object.
You can make use of Json libs like
Jackson ,
Gson etc
But you must know that REST application doesnt end with just handling the request and response , but it needs to take care of other non-functional requirements like
Authentication
Authorization
Security etc
Building this from a scratch from a Servlet is overkill and waste of time when there are ready made frameworks that these things for you
My favorite is Spring MVC 3.0
Check their project site for more details
Just to show you how easy to set up one in Spring MVC , check this below tutorial
Spring 3 REST Tutorial
Pls rate the post if it helps , Cheers.
If you want to go with Java, I suggest that you take a look at JAX-RS... And since REST is a complex topic, here is a url with tons of informations on it. http://code.google.com/p/implementing-rest/
As a complete beginner, I believe the best way to implement a (nearly) RESTful API without having to read a lot is simply to implement the API just using HTML pages and HTML forms with the back-end processing to handle them.
The rules are:
Use <a> tags to provide links to related resources. (navigation)
Use <form> tags to initiate any kind of processing operation on the server. (actions)
You can then make it properly RESTful by using progressive enhancement to add Javascript AJAX requests that perform PUT, PATCH, and DELETE instead of using POST for those three (of course, keeping POST for creating resources where the client doesn't know the resultant URI).
You can then click around and test the API in a web browser! Tools like Selenium can automate this.
If you need to provide JSON, this can be added after the API has been designed and tested, although libraries exist to process HTML or XHTML responses too, so JSON isn't necessarily required for machine readability.
if you are using php with symfony try:https://github.com/FriendsOfSymfony/FOSRestBundle this lets you create a real REST full servicer very quick.
Vogella made my day very easy when i started Web services with an super example here with eclipse screen shots ..Have a look here.
I am a newbie with ExtJS 4. I am having problems understanding the implmentation for the "/" syntax for the URL in a Rest Proxy.
For example when using a REST type Proxy the URL config in many examples is just "/users".
I'm confused by this and can't seem to understand it's implmentation. I'm expecting to see an actual executable ".php" or such URL which I have used successfully in an Ajax Proxy. In other examples I see "app.php/users". I understand the php file which I expect but the "/users" part I don't understand. I've spent a few hours trying to find the answer for this but nothing I found has defined it for me.
I'm sure the explanation is very simple.
Thank You in Advance.
For the full explanation you should study up on REST.
Something like /users is standard usage for a REST HTTP request, it is not just ExtJS implementation. Specifically to answer your question, the reason no file extension is included is to denote that this is a logical url, i.e. there is not a physical users.xml file necessarily, instead it is dynamically generated using RESTful webservices.
In other words, you would need to set-up a RESTful webservice architecture to use this ExtJS proxy configuration.
The link above and this tutorial on implementing RESTful webservices with Java helped me alot.
EDIT:
I found a better tutorial (I think) here, also showing implementations in something other than Java.
Like SOAP which as a WSDL which allows you generate code that will help create request, is there any mechanism in REST which allows you to document the payload or response of a REST API call?
Most services that provide REST APIs, seem to provide samples to explain the structure.
What is the best practice for REST APIs.
If you're returning xml, you can simply provide an xsd. There is also wadl, which some frameworks will generate automatically.
I find the best practice is providing samples (or links to samples) to explain the structure. Developers working against your API then need no extra tools or workflows to know how to interact with each part of your service.
Striving to ship a well documented application, I'm looking for a good way to describe a REST API for my Grails Application users.
I know that REST calls should be simple enough to be described by examples, but it doesn't feel formal enough.
I've spent a couple of hours looking for a solution suggested by other Grails users, but didn't find a neat solution besides a recommendation to use WADL or WSDL 2.0
This looks like a good direction, but there must be a simple way to do it in Grails.
I'd appreciate some guidance for a process to generate a REST API based on my model objects preferably with the ability to filter or control the exposed fields, plus, a nice graphical way to present it (something like the XSD Eclipse plugin)
Thanks!
Guy
I would suggest to avoid WADL or WSDL for API documentation, you can see this question where I explained my reasons: Why the slow WADL uptake.
WADL or WSDL are usually used for automatic client code generation, they are not human readable documentation. I don't think WADL or WSDL are very useful for a user to figure out how to consume the resources correctly.
I prefer the good old html documentation, for example I like the way twitter documented their API
If you insist on automatic generation of resources documentation I can recommend on the ATOM service document. Many REST framework can generate it automatically based on the resources annotations. (e.g. Apache Wink)