I've been looking at asp.net Web Api, and I like the simplicity of implementing a practical web service.
However, how can I document/specify the interface of a service implemented like that? For example, is there any spec I can pass on or generate to a Java guy with no .NET background that will let him easily call and consume the service? What can I give to the javascript guy?
Ideally, I'd like the benefits of SOAP/XSD or something like it (easy to deserialize with nicely typed objects) for the java guy, while retaining a service that's callable from a web browser too (i.e. supports non-crufy JSON).
Update
It's worth noting that since I originally posted this question, I discovered ServiceStack which deals with this more naturally; supporting JSON, SOAP, and WSDL out of the box for the same service, as the client chooses. If you really want SOAP+JSON, it may be a better framework than ASP.NET Web Api.
Update March 2016
It has been a while since this was answered and the tooling for documenting any Rest API has come along a lot. We are currently evaluating Swagger 2.0 now spawning out to the the Open Api Initiative, RAML and API Blueprint.
For WebAPI projects there is a tool Swashbuckle that auto creates Swagger (Open API) format documentation.
Format for documenting a REST service:
There are some attempts at structuring and standardising the description of REST services:
Web Application Desciption Language (WADL)
Web Service Description Language 2.0 (WSDL 2.0)
I think it is fair to say neither of the two approaches above have very wide adoption, but WADL does look like a nice concise format - a quick XSLT over the top and it could be a nice human readable format. There lots of examples of WADL for some famous API's at the apigee github site here.
When trying to find a documentation format that is appropriate I tend to look for "inspiration" from others.... Apigee do a lot of research in this area and have this as documentation for one of their API's here or take a look at Facebook's social graph api here.
The examples are largely in line with the advise here
How to auto document:
Using .NET: There is a good example of auto generating a WebApi "help" page here. A logical extension of this example may be to get it outing a WADL formated version as well...
Using Java: Jersey is a tool used in the Java community to generate WADL automatically.
What to share with the other developers:
Your Javascript guy will most likely want a manual like the Facebook and apigee one; giving the dev examples of the resources, urls, response codes etc. The most important thing here will be supporting JSON as the primary content type this will be the easiest for him/her to consume and work with by far.
Your Java guy would also want the manual, but also in theory they could be given example XSD for any XML representations of the resources you send/consume (assuming they make the request as "Content-Type: appplication/xml"). This may help them build proxy classes etc. JSON to Java and .NET converters are available online and given the example resources in your manual they should simply be able to use one of these types of services to quickly create proxies. Generate Java class from JSON?.
If you absolutely must have auto discovery, auto proxy generation etc then you may need to offer a choice of both REST and SOAP (with WSDL) endpoints - relevant question here: ReST Proxy Object Generator.
You can use IApiExplorer interface and ApiExplorer class in order to create a help page for your Web Api service. This help page will describe the REST methods exposed by your service so any developer who understands how REST works will be able to use it (regardless the language). Please read below links for details and samples:
ASP.NET Web API: Introducing IApiExplorer/ApiExplorer
ASP.NET Web API: Generating a Web API help page using ApiExplorer
Documenting your ASP.Net Web API’s
Related
Our RESTful application need to support 'partial responses' to limit bandwith.
By this I mean that the REST client tells the URI service which fields of the resource it is interested in.
For instance: api/v1/users/123/fields=firstName,lastName,birthDate
We're using Jackson parser to convert our DTO's to a JSON structure.
The problem is that we cannot tell at runtime to 'skip' some properties.
We should need to create a class at runtime with a variable amount of properties to accomplish this. But I don't think this is possible in Java, it is a static language after all.
While searching the internet we found some semi-solutions by just returning a java.util.Map containing the requested properties or filtering out properties by the Jackson parser.
Especially the latter seems a 'hacking solution' to me. It seems that Spring MVC doesn't provide an out-of-the-box solution for this issue...
Is there any alternative in the Java world we can use to solve this issue?
How about Yoga
Yoga extends JAX-RS and SpringMVC RESTful servers to provide GData and LinkedIn style field selectors.
Choose which fields you want to see at call-time
Navigate entity relationships in a single call for complex views
Much faster speeds in high-latency (e.g. mobile) apps
Streamline client development
Browsable APIs
this seems pretty basic, but I am rather new to web development so I am a bit stuck here. I have MongoDB running on the backend, which contains geo-spatial objects that in the front end should be displayed on a map. The communication between backend and web frontend is where I have knowledge gaps.
The user should be able to zoom to an area on a map that he is interested in, then press "Search". The backend would then find every entry in the database that has coordinates that are on the users current screen. It would transmit these to the frontend, ideally as a list of JSON objects. The frontend displays these on a map.
I have a front end mock up, code that puts data into MongoDB and code that queries MongoDB. I know that I am missing a server that can be queried from the frontend. I thought I use Jetty. But what do I need to do then? I guess I need Jetty to provide a JSON API that I can query from JavaScript. Could someone point me to the Jetty class or interface that I need to implement and maybe give a few lines of code on how to query this from JavaScript?
You have a very open question here.
To start with, Jetty is merely a Java Web Container (following a subset of the Java EE Web Profile), while it does have some AJAX/JSON capabilities, it is extremely fundamental and not hooked up into any sort of query API.
You would do better do use Jetty along with a proper REST/JSON API library for your project.
Some examples (these are not the only choices available):
jersey - Jersey - an Open Source JAX-RS (JSR 311) implementation for RESTful web services, with JSON Support - Here's Lars Vogel's Tutorial on JAX-RS using Jersey.
restlet - Restlet - another RESTful web API, with a JSON extension
resteasy - RESTEasy - another JAX-RS implementation for RESTful web services, with JSON marshalling.
Also note that there are many flavors of Java based JSON APIs and Libraries, you should probably be aware of them as you will encounter them in your journey to success.
In the end I found the Dropwizard framework (there might be others), which does a lot of the work that is necessary to get a simple JSON API up out of the box:
http://dropwizard.io/
I am currently implementing a set of web services intended to be used by JavaScript clients and am using Google Gson for JSON serialization/deserialization. My service contracts are thus defined in Java classes. I now need a way of generating documentation of these message interfaces in a way intended to be used by JavaScript developers.
Ideally, I would like a tool along the lines of JavaDoc that generated JSON examples, JSON schemas or other Web developer friendly documentation of my types, that could easily be integrated with Maven to produce HTML based documentation for types with a certain annotation.
I can point them to the generated JavaDoc, but it will require them to understand and hunt through all private fields to work out how to format requests, and also does not take into account Gson type converters etc.
Are there any relevant tools available in this area?
I have used Swagger in the past. It is simple to implement, yet generates powerful API doc.
Please look at this documentation. I think this is what you are looking for.
http://petstore.swagger.wordnik.com/
I am getting started researching / creating a groovy portlet that will connect to a REST based ESB service that returns JSON; I will also need to pass the username in the headers. I was wondering if there are any examples out there on how to create the portlet and set the headers? I am new to groovy and from what I understand this can be accomplished rather easily. Essentially I want a portlet that will allow a user to search for a widget via a search box and return a list of matches. Not sure that it matters but the portlet will be deployed to the Vignette Portal. Any info would be much appreciated!
Thanks in Advance!
Doing a portlet with Java/Groovy is very doable with Spring Portlet MVC. I used some sample code from various sources a year ago but googling on it will give you more modern examples and let you pick something more applicable to your app. The real issue comes up with how you plan on building your app. Gradle is the best option for writing a Groovy web app.
However if you are talking about using Grails, then it becomes much more difficult and I would not advise learning Grails as you are trying to get it jammed into a 'portal' implementation. There are plugins for Liferay and 'portlets' in Grails but when I last looked at them earlier this year, they did not seem fully baked.
Calling REST based services with JSON or whatever from your server code doesn't have to care that you are in a 'portal'. The big issues comes up when you are trying to create the UI with your portal provider specific APIs. Don't be fooled into thinking you won't be using portal specific stuff. We used Liferay a bit and from my perspective the Portlet spec was very slim so to do much of anything interesting in a portal, you have to use some portal specific stuff, at least for UI and authentication services.
So my suggestion is build a Gradle Groovy Web project and use the Spring Portlet MVC Java examples to get something going and then you can simplify with Groovy as it makes sense. Initially you might want to simply start with Java if that is your comfort zone because integrating with your portal might be daunting enough without trying to learn a new language to boot.
I would like to know, what are the ways a web framework may be suitable for designing a RESTful app, in general.
One goal is for example to provide http request routing, so they are automatically sent to appropriate controllers. From architectural point of view, web framework based on MVC pattern are more suitable for REST.
What other features of web frameworks are helpful by building apps satisfying the REST constraints?
Is there any reason why you consider certain languages(python/java) or web frameworks(django/turbogears/jersey/restlets/...) as the most applicable ones?
I think the best way for a web framework to support a RESTful style is to automatically map the different HTTP verbs (GET, POST, PUT, DELETE, etc.) to corresponding methods on its controllers/request handlers. Most modern Python web frameworks do this out of the box, with the notable exception of Django (unless I missed a dramatic change).
a) You need very flexible routing.
b) You need to be able to easily generate links that correlate to resource controllers using templates and parameters.
c) The server should help you to parse all the http headers. e.g. Authorization headers, Accept headers, language headers, cookies, etags.
d) It should support serializing and deserializing all the commonly used mime types.
e) It should help parsing parameters from incoming URLs
f) It should help resolving relative urls based on the request url and any available BaseURL.
There are few ways that a web framework can NOT support REST. Its basically written with the HTTP model in mind; so just about any web framework works. The automatic routing you mention is a common expectation, but not strictly required for REST.
I would stress the ability to directly support definition of resources. In Ruby on RAils you can define a resource through scaffolding and you get a model with controller with restful verbs implemented also with views and support for different formats and readily avalaible views and routing with ids.
Aside from that having access to HTTP and supporting principles of HTTP is what you need.
I am not experienced enough to know about support in frameworks, but it would be also nice to have support for the caching and other request options.
On the “specific software recommendation” front, I've had people recommend Apache CXF as a framework for building RESTful services with Java. It appears to be even able to simultaneously support SOAP (which happens to be very useful for helping some of our customer base adopt the software). I'm still in the experimenting-with-it stage though, so you may be able to do better.