Can tools like swagger be used for Json rpc documentation. Or are there any other better tools?
Related
I'm looking to get familiar with the Amazon Connect API. I've seen the reference below but it's difficult to use for me because the navigation is a flat, alphabetical list of endpoints ordered by action instead of resource. Of note, the endpoints are alphabetized beginning with "Delete", Get", "List", "Update" and others, while it would be great to have these grouped by resource.
I'd like to reorganize the docs which can be done by editing an OpenAPI or other API specification and adding tags for each operation. I looked though the reference and conducted a few searches unsuccessfully.
I'm using the following API Reference:
https://docs.aws.amazon.com/connect/latest/APIReference
Any other spec format such as RAML or a proprietary format would be okay as well. For example, Google provides their own "Google Discovery Format" which can be converted to OpenAPI. The following is mentioned at https://googleapis.github.io/ .
OpenAPI
We recommend using OpenAPI and OpenAPI-based tools for working with Google’s REST APIs. Several tools for converting Google Discovery Format to OpenAPI have been published:
google-discovery-to-swagger, an MIT-licensed open source script for converting Google Discovery format into Swagger 2.0.
API Spec Converter, an online converter from LucyBot.
The API Transformer from APIMatic.
Google’s OpenAPI tools include gnostic, a front-end for OpenAPI tools that reads OpenAPI descriptions, puts them in an efficient binary representation, and allows efficient plugins and standalone tools to be easily written in any programming language with Protocol Buffer support.
Is there an OpenAPI or other spec available for this API? If there is, I'd like to update it with tags and then render it in an easier to consume format.
Update: Aossey notes that Amazon doesn't publish OpenAPI specs for their APIs. To address this, I've started to assemble some information in the repo below, potentially resulting in an OpenAPI spec. Feel free to contribute.
https://github.com/grokify/amazon-api-specs/blob/master/connect/endpoints.csv
The short answer is no, there is no OpenAPI spec for these APIs.
These functions (listed in the docs you linked) are implemented in AWS SDK and the AWS CLI. While there are underlying HTTP endpoints, they are not easily consumable in the way you're most likely looking for. The SDK and CLI take care of authentication/authorization (via IAM service) and request signing for you, which you would have to implement yourself if you were going to leverage the endpoints directly.
I'm confused between the concepts of Odoo RPC, XML RPC, JSON RPC, and REST API in the domain of Odoo. To my knowledge, these are the only 4 APIs that can be used in Odoo.
In Odoo's documentation, only xml rpc and json rpc are mentioned. But on this website: Odoo RPC They've discussed Odoorpc library. Fourth one is REST API, how does it fit in odoo? When we create a controller with a specific route, would it be called a REST API?
RPC and REST are different approaches to how to call an API. RPC is a bit harder to use but more powerful, REST is easier but less powerful.
Odoo only has one API: RPC. Odoo has no REST API.
You can call Odoo's RPC it through XML-RPC or JSON-RPC, but the API is the same. Just use the format that best fits your other system. In case you don't care, go for JSON-RPC, which is the one odoo itself uses.
The docs you link are unofficial, and the odoorpc lib is another unofficial library that makes interacting with odoo API more comfortable. These are the official docs: https://www.odoo.com/documentation/14.0/webservices/odoo.html
Currently I am working on a REST API and noticed, that for real REST it is essential to provide the possible HTTP operations of the resource within the HTTP response (e.g. in JSON-LD format).
After playing around with Swagger, I got to JSON-LD and Hydra, which in combination provide the foundation for real REST.
The problem with pure JSON-LD and Hydra is, that there is no real editor (the Playground does help for testing but not for editing).
Then I found Api Platform which sounds quite promising but I could not find any hint, that it supports real REST.
Does API Platform support HATEOAS in terms of providing the possible HTTP operations?
API Platform explicitly supports HATEOAS and they even encourage using Hydra. Their admin UI supports viewing the API through an OpenAPI lens or a Hydra lens.
These days everyone is making REST applications. So far i used only swagger editor for generating those files.
Does anyone know if there is good mature tool or IDE that thave ability to visually design Swagger REST APIs and then generate the Swagger Specification YAML specification file?
Tool can be commercial or opensource
I am using https://studio.restlet.com for that.
It is a great tool and it is pretty in intuitive..
You can do export/import from Swagger and RAML.
I'm using postman for testing api. Postman collections can be exported and transformed to valid Swagger 2.0 YAML on https://apimatic.io/transformer.
Exported YAML file then import on swaggerhub https://app.swaggerhub.com were changes can be made if needed.
Folders from postman are transformed into tags, request models are generated by body of request and response examples can be used to document different error responses.
I know that REST doesn't have WSDL document as SOAP has (some has WADL but not all, and it is not that common)
Is there a tool that take REST documentation (REST uri maybe) and generate describing document for that web service?
The tool swagger https://editor.swagger.io/ is able to do it only if added annotation to the source code of the web service not to any REST web service.
In short there is no official/REST approved way of doing what you are looking for.
WADL, Swagger and RAML are all "proposed" ways of achieving WSDL like functionality in REST, however they are proposed and not wildly supported by the development community.
If you were to start a new project these would make sense but if you want to run it on top of a existing project and generate some documentation you are pretty much out of luck.