What is the difference between swagger-api and JAX-RS ?
Is the swagger-api only for documentation? (for example #ApiOperation)
As per the API docs, JAX-RS is the Java API for RESTful Web Services that provides portable APIs for developing, exposing and accessing Web applications designed and implemented in compliance with principles of REST architectural style.
Swagger, on the other hand, comes in picture when you have implemented your restful web services using any of the JAX-RS implementations (Jersey, RestEasy, Apache-CXF, etc as already mentioned by #Bijoy). Swagger adds form to your APIs by making them look good and presentable so that client code can be written easily, at the same time it also makes documentation a much less boring task by integrating it with code. Needless to say, also saves the extra time it takes to document if done after coding is over. In this sense, it is a bit revolutionary.
jax-rs is REST specification, and it is implemented by ones like jersey, resteasy etc, swagger is more on documenting and it has an easy interface if you want to test and make lot easier from different platform for adapt your rest functionalities
Related
I am very interested in Integration Platform as a Service.
As we know, it is possible to generate an API spec from an API. Is the opposite possible?
I want to write a piece of software that automatically create some functions for calling the endpoints of an Open API. In order to achieve that, the piece of software should consume an API spec and generate the code. Theoretically, this could be possible, if the spec covers all endpoints with all parameters of the API, etc. but:
this is often not the case
specs are written differently from each other
My question is: what should my software consume in order to get reliable information about the API endpoints, parameters etc.? Is there a standard for that? Is the API spec the way to go?
Look at Github Copilot. They're able to generate pretty descent facsimiles of functions from API spec. Just a word of caution, the function might not be 100% accurate and so you'll still need to check over it.
In a properly designed webservice there are at least 4 layers, presentation, application, domain and infrastructure.
REST documentation describes only the presentation layer's outer surface: HTTP interface and operations, so it is not possible to generate a complete webservice based on the REST API documentation. If your application does not have any kind of logic, it is just a data structure and CRUD, then it is possible, but in that case you'd better to find a database which has a REST API and very good access control and problem solved mostly.
If you have some sort of standard documentation like WADL or JSON-LD with Hydra, then you can generate a REST API skeleton for the presentation. I just googled the topic a little bit, maybe this thesis can be useful for you: https://repositorio.ul.pt/bitstream/10451/35311/1/ulfc121800_tm_Telmo_Santos.pdf
Is it possible to produce/generate documentation using API Blueprint tool from Restful API code and If so how to use this tool any help?
If you are looking for a way how to generate a description of your API from the code then API Blueprint isn't probably the best choice as we believe it should represent the contract between everybody involved in the API design lifecycle. This is also the reason why we have built the testing tool – Dredd – https://github.com/apiaryio/dredd
With Dredd you can test your API implementation is matching to your blueprint. It wouldn't make much sense if the blueprint would be generated from the implementation.
Hope this does clarify.
One of the crieria we are using when deciding between using REST and SOAP (RPC) style services is not just programmer convenience, but which is easier to test using Automated test tools. It seems there are lots of good tools for both, but is one inherently easier?
RESTful APIs are usually simpler, and built on top of well developed technologies that are easy enough to test (specifically, HTTP), so I would say RESTful APIs may be simpler to test. You can even do most of your testing with just a web browser, so I think that's pretty simple.
We are currently designing a REST API that we want to publish in a few months. Since this is a brand new application we can choose any other programming language other than PHP. At this moment we are using the following link to have a base of best practices for APIs.
What is the most suitable Rich Internet Application Programming Language to construct a REST API? I know you can accomplish this goal with almost any PL, we are looking for one that will give us the base. And while you are at it, if you can point the second better and the reasoning that will be perfect.
Thanks SO for this great website.
EDIT 1: Other link related to this question.
Depends on what your team is comfortable with.
You really can't go wrong with Ruby on Rails or Microsoft .NET (using WCF with REST endpoints).
Ruby on Rails is good if that architecture works for your application and you only need that REST endpoint.
With .NET, you can create the REST endpoint for your WCF service but also provide other endpoints if you find you need them.
I actually don't think you could use an RIA language to build a REST API, because a REST (Web) API is an collection of resources served via an HTTP server. An RIA usually runs client-side.
So I assume you're asking what's the most suitable programming language to build a REST API which will be used by an RIA.
There are many good choices. I'm not sure what your parameters are, so I'll suggest what I would use if I needed to build a REST API.
Some good choices:
Java, using the Restlet framework. I use this all the time and I'm very happy with it.
Ruby, using the Ruby on Rails framework or the Sinatra micro-framework
Python, using a micro-framework such as Bottle, djng, itty, juno, mnml, newf, web.py, or Werkzeug. It's definitely possible to use a full-blown framework such as Django or CherryPy, but I've found them to be not particularly well suited to this use case.
Hope this helps!
If not PHP, then Ruby or Python.
We are developing a middleware SDK, both in C++ and Java to be used as a library/DLL by, for example, game developers, animation software developers, Avatar developers to enhance their products.
Having created a typical API using specific calls for specific functions I am considering simplifying the API by using a REST type API (GET, PUT, POST, DELETE) or CRUD type (CREATE, READ, UPDATE, DELETE) interface.
This would work in a similar way to a client-server type REST API where there are only 4 possible API calls but these can take flexible parameters.
This seems to have the benefit of making the API stable in that new calls are not being added and old calls are not being removed. So a consumer of this API need not worry about having to recompile and change their code to suit any updates to our middleware.
The overhead is that there is an extra layer of redirection in the middleware controller to route API calls and the developer needs to know what parameters are available for each REST call (supplied of course).
I have not so far seen this system used outside of web type client server applications so my question is this: Is this a feasible idea?
I am thinking in terms of its efficiency as well as if for example a game developer would find it easy to use.
Yes, this is a feasible idea. But I'm not sure the benefits would justify the costs. REST is best applied to a networked application scenario, oriented around requests and responses. While there are definite learning curve advantages to a uniform interface, those advantages can be present in almost any well-designed API which provides reasonably abstract procedures.
You also expressed concern for whether a game developer would find a RESTful API easy to use. I'd be dubious. I've implemented many RESTful web services, and helped many developers get up to speed both building them and using them, and the conceptual leap required to grasp REST can be substantial for someone who has been steeped in procedural APIs for years. I'd think that game developers in particular would be very strongly connected to procedural APIs, to the point that attempting to adopt a different paradigm, whatever its benefits, might prove extremely difficult.
Remember that REST is not specific to HTTP, and does not rely on just the 4 HTTP verbs. The verbs you have and can use depend on what protocol you're using.