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.
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
When I am looking into approach's used for the development of API's, I came across multiple approaches like Code-First, API-First, Design-API-First.
I clearly understand Code-First approach how it is different from other two. But I am not able to get the exact difference between API-First and Design-First approach.
Summary from links:
API First:
API's are considered as first class citizens by the organization.
You design each of your APIs around a contract written in an API
description language like Open API for consistency, reusability, and broad
interoperability.
Design-API-First:
Describing every API design in an iterative way that both humans and computers can understand before you write any code.
API design-first is about the process of creating the API itself.
In design API first approach there will be lot of collaboration in designing of the API.
My understanding by far:
I feel 1 and 2 points of Design-API-First is saying same thing as API First because for example Open API specification is understood by both humans and computers. Is there anything more to it?
So, the only difference there will be collaboration added here by involving stakeholders, developers, customers etc?
So, when we use Design API First, we can say we are also using API-First?
References:
Probably I am able to get the exact context from the following links,
please use them and see if you can get the right understand of it and
address this question.
https://blog.stoplight.io/api-first-vs.-api-design-first-a-comprehensive-guide
https://blog.axway.com/product-insights/amplify-platform/application-integration/api-first-design-api-first
https://www.ecosmob.com/design-first-or-api-first-where-does-future-lies/
I'm about to set up an AWS API Gateway via Cloudformation and wondering what is the better solution:
should I use the AWS Resources for Resource and Methods or is the better approach to import the well known OpenAPI (Swagger) file we have into the API Gateway Resource?
From my researches I found out that Using swagger has some limitations (https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html) but on the other hand its kind of the standard to create APIs.
So going full in on AWS Cloudformation might have some disadvantages I cannot see right now. Thats why I'm asking for experiences from someone who was in the same situation. Grateful for any guidance...
Merci A
Personally I find the best way to develop api gateway resources is using the Serverless Framework its super easy to use and integrates very easily with other AWS services i.e. Lambda.
Also under the hood serverless is just cloudformation templates so its very flexible.
Nowadays you can write your templates using SAM (Serverless Application Model https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html) if you don't like the serverless framework.
Some of the benefits are that you write less cloudformation code and you can locally debug/test your lambdas/step functions.
Here is my two cents on the best practice among your solutions:
While developing products, swagger or apiary are great tools to document your API and quickly mock the API before implementing them. With a mock API and documentation in the hands of (say) a product manager, it becomes easy to get started with a solid plan for development. But tools like swagger can auto-mock an API specification and if you wish to import this specification only to mock an API, then this import feature is a great tool to use, otherwise it is not. Let me explain why.
By importing an API and orchestrating AWS resources directly from swagger, you bring in lots of limitations, the primary one being your development process does not include a framework such as serverless or zappa. This would force us to directly write lambda functions using AWS console or AWS cli, and make the project architecture complicated.
In writing lambda functions without a framework, if we know upfront that our functions would be orthogonal to each other and do not share much common dependencies, then great, this would work, but for any project with (say) a database, functions accessing external API, some endpoints being guarded by an authorizer and having other resources, using a framework is definitely the better option. It is easier to create layers and common code, for example a database wrapper class.
When using any framework, it is better to start with the framework boilerplate and make the implementation to match the documentation. By studying the advantages and limitations of that framework, we can decide if it fits our architecture.
Also, IMO, this method is not widely used, and finding help might be tough later on as the project becomes more complex.
hope this helps.
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
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.