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.
Related
I'm currently working on developing connector for the surveymonkey Rest API. Is there any OpenAPI Specification file for the same that has all the endpoints as per the docs? If not, can I get it in the near future?
In researching the same question, I discovered that you can export the Survey Monkey collection from Postman as a JSON file, then convert it to OpenAPI format using this tool: https://kevinswiber.github.io/postman2openapi/.
Postman is working on a new feature to make this functionality available directly within their tool as well.
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.
I'm thinking about trying to implementing a client for a particular json-rpc 2.0 service that could give a user some static typing guarantees. The API in question is very large, so actually writing a full-featured client by hand with all the necessary type information too big of a task for me to be bothered. However I've found via an undocumented http endpoint a large json based schema that seems to describe the entire json-rpc service fully. I'm certain I could write some sort of code generator using this specification. It is too big to paste here.
My question is, is there a standard specification for describing a json-rpc service? I've had a search around and I find a lot of dead links and the official spec[1] for json-rpc makes no mention of a standard schema definition for such a service. The schema I've found seems to be at least partially based off of the json-schema specification[2].
json-rpc
Json Schema
JSON Schema is great for defining payloads formats (you can even use it for REST APIs in OpenAPI) but indeed it won't help describe the "RPC" part, with the methods and entry points.
OpenRPC, created in early 2019, seems to be the most promising
The Ethereum Classic Labs Core (ECLC) team recently created the OpenRPC Specification, aiming to improve all blockchain dapp development. The specification emulates OpenAPI, the successful and widely adopted specification for REST APIs.
The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs.
Other approaches
Drupal JSON-RPC module provides a discovery endpoint and a Postman collection
The available RPC services along with documentation and usage details can be discovered by sending an HTTP GET request to /jsonrpc/methods.
You can use this Postman Collection with examples and tests.
There might also be interesting things to get from AsyncAPI, gRPC, GraphQL.
Dead
Also citing some other options I stumbled upon but which are dead:
JSON-WSP seems outdated, the Wikipedia page is pending deletion (talk page seems to say this was never actually a standard)
JSON-WSP (JavaScript Object Notation Web-Service Protocol) is a
web-service protocol that uses JSON for service description, requests
and responses. It is inspired from JSON-RPC, but the lack of a service
description specification with documentation in JSON-RPC sparked the
design of JSON-WSP.
JSON Schema Service Descriptor seems to have remained a draft
A JSON Schema service descriptor is simply a JSON Schema with the additional definition for methods.
A bit late but is this what you are looking for?
https://github.com/open-rpc/meta-schema/blob/master/schema.json
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.
We use Swagger-based REST API specification for different projects. So each project has its own Swagger UI with a description of endpoints. All these UIs are deployed on different servers, under different domain names, which is not cool at all from the organisation perspective.
Are there any nice options to store multiple Swagger specifications in a single place? It could be any service for a REST API descriptions management, which consumes the Swagger Specification.
I found some nice options for a REST API specifications management:
Apiary (apiary.io)
Restlet (restlet.com)
SwaggerHub (swaggerhub.com)
All the three services support the OpenAPI Specification, which is based on the Swagger 2.0 spec.
Apiary has a good collaboration management and supports a REST API validation.
However, it is pretty expensive. A suitable plan costs 99$ per month: apiary.io/pricing
Restlet also has a possibility for a collaborative work and it supports a functional testing.
Comparing to Apiary, Restlet has a better choice of pricing options: restlet.com/pricing
SwaggerHub is the most optimal choice in my case. It is designed especially for multiple Swagger specifications management. The service has a support of all the code generators developed for Swagger. Nevertheless, it does not provide REST API testing/validations tools unlike Apiary and Restlet.
The biggest advantage of SwaggerHub is pricing. A ratio of specifications number per $ is the best with a maximum number of 25 collaborators on each API: swaggerhub.com/prices