Google APIs have published human-readable documentation and also machine-readable JSON schemas, for instance https://www.googleapis.com/discovery/v1/apis/urlshortener/v1/rest. I am looking to auto-generate API clients for AWS cloud services for a language that does not currently have an API client. For this, I need a machine-readable description of these APIs.
Is there such a schema available?
Some of the AWS sdks work in this way, for example the ruby sdk includes json descriptions for all of the API methods, arguments and return values.
I don't know if this representation is considered public (in the sense that newer versions don't change this schema) but it should be possible to generate an API client from it given that this is how the ruby sdk is built.
AWS has JSON service descriptions here for all AWS services. These are automatically generated and kept up-to-date from the AWS backend, and consumed by the official aws-cli and Python library Boto3.
Related
I am working on AWS cloud platform. My application is written in Java. My task is to get secret stored in secrets manager. I have implemented this in AWS java version 2. But it has many jar dependencies around 20 jars. I would like to know is there any support for rest api by AWS?
My company does not allow calling the external API directly. The API call must go through API gateway. To request the API integration, I have to submit swagger or YAML documentation with all end points.
I have BigQuery API reference document - https://cloud.google.com/bigquery/docs/reference/rest.
Please assist with where I can find the swagger/yaml doc.
I've not generated OpenAPI (formerly swagger) docs for Google APIs but it should be possible.
Historically, Google published descriptions (schema) for all its services using so-called Discovery documents. Here's BigQuery's page on APIs Explorer. It includes the discovery document for BigQuery
Increasingly, Google's services are now defined using protocol buffers and Google uses gRPC|HTTP transcoding to surface the API as REST and I know that, when Cloud Endpoints uses this, the API is described using an OpenAPI document too.
But, I'm not aware that Google publishes its APIs as OpenAPI documents directly and think you will probably want to convert the Discovery document into an OpenAPI document.
In theory an annotated (with REST methods) Protocol Buffer document would be functionally equivalent to a Discovery document and could be used instead but there aren't Protocol Buffer documents published for all Google services and evidently not for BigQuery.
This document is comprehensive and references tools that generate OpenAPI documents from Discovery documents. I can't attest to any of these as I've not used any of them:
https://github.com/googleapis/googleapis.github.io#openapi
As far as I understand, there are only three ways to access AWS resources:
Management Console (browser)
AWS CLI
AWS SDK (in various programming languages)
However, why did not AWS provide REST APIs and their reference document so that we can interact with AWS resources directly using a REST client like Postman?
I think they are using REST APIs behind the scenes (All the above three interactions actively use REST API I guess).
Thanks in advance.
There is REST API documentation available as well. Its just that AWS officially encourages the use of more abstract methods such as using CLI and SDK since its easier to use as well as they are maintained by AWS.
Also using the sdk or cli is encouraged because they are perfectly interfaced with the aws rest api with extensive testing and covering all cases. And you don't need to focus on stuff like what headers you need to attach or what should be the request body format. Users can focus on writing their own business logic.
The only source I could find for documentation of rest api are the official docs which I have linked below. Since the direct use of rest api is not preferred hence no commonly available tutorials. I don't think there is anything extra which can be accomplished using the rest api which the cli or sdk doesn't already offer.
A more practical example would be aws s3 cli. It has a lot of underlying implementation which speeds up the process of uploading and downloading, like establishing 10 network connections in parallel to utilize the complete network bandwidth etc. This you would have to implement yourself if you are directly using the api.
Some Examples:
S3 REST API
EC2 REST API
Similarly there is API documentation available for every service.
I have created API using AWS Api Gateway. Then i have documented documentation parts for all the entities ( like API, RESOURCE, METHOD, MODEL etc). Then using AWS Gateway Console i have published the documentation to dev stage with version 1
But i am not sure how do i (or the consumer of the API) going to access the documentation?
There is an Export option that can export documentation as Swagger or OpenAPI3. This will create .json or .yaml file and then consumer has to import these files into swagger UI. However this is not user-friendly option to provide swagger file every time i update documentation to all consumers.
I was wondering, after publishing the documentation is there anyway consumer can access documentation directly via http. So lets assume my dev stage api URL is
https://devapi.example.com/v1 so something like https://devapi.example.com/v1/help should launch Swagger UI with latest published swagger file.
Update 1
In ASP.NET Web API or .NET Core you can include Swashbuckle that creates swagger files and also has embedded version of the Swagger UI tool. So after deploying API user can access documentation directly from UI something like https://devapi.example.com/swagger.
I was hoping the same thing from AWS gateway. After publishing the documentation it should make that documentation available via some predefined resource path.
AWS API Gateway can only make documentation exportable but won't render a UI app. There is no endpoint that you can use in the gateway to render the documentation. You may wish to use third party tools or AWS API Gateway Developer Portal to allow users browse API documentation. You may find this blog helpful.
Micro Swagger imports swagger spec from Amazon API Gateway & serves a swagger UI from it.
You can leave it running on an EC2 instance:
npm i -g micro-swagger
micro-swagger start
It'll use the instance's IAM role to download the Swagger spec from API Gateway. Your CI/CD pipeline can restart/refresh Micro Swagger whenever it deploys. Your customers can see the latest API docs at the instance's domain.
I would like to add Amazon services to my CodeName one App, I have downloaded java-SDK from Amazon and added a library to my App. Everything working properly in simulator once I gave Android build.
If I try to access Amazon AWS in my android app I'm getting an error like "NoClassDefFoundError".
Here my question is CodeName one supports Amazon AWS or not.
If Codename One supports integration with Amazon AWS then how can I integrate and use below AWS services
Amazon Cognito,
Amazon Cognito Sync,
Amazon API Gateway,
Amazon DynamoDB,
AWS Device Farm,
Amazon SNS(Simple Notification Service),
Amazon Analytics.
You can't just add an arbitrary JAR to Codename One, because we don't support all the features of Java SE as explained here.
There are two ways in which you can support Amazon and you can see samples of both approaches in the libraries section of Codename One.
Wrap the native Android/iOS libraries - there is a long tutorial for this here and in the developer guide.
Wrap the webservice/JSON API's which is a better approach in many regards as it is 100% portable and will bring you into platforms like UWP, Desktop, Web etc. This is the approach taken by parse4cn1.
Option 2 is superior for solutions like AWS as it's much easier to debug and doesn't require any native code etc. Ideally we'd love to have a proper AWS cn1lib similarly to the parse cn1lib.