At my current company, we extensively use OpenAPI and Stoplight Studio to define API contracts.
We are now starting to use message bus concepts, and would like to keep using Stoplight Studio for message definitions too.
I can't see anywhere on the Stoplight Studio website that specifically mentions message bus, or messaging.
Is this scenario supported by OpenAPI?
Not sure about "Spotlight Studio" specifically, but Async API was designed to bring OpenAPI style contract definitions to Event Driven Architectures.
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.
We are used to that any NLU service integration with Botkit should be implemented as middleware. This is a fairly obvious approach.
Botkit Studio has added LUIS support out of the box recently. And that approach confuses me.
Depending on the resolved intent, I want to make an API call, passing extracted entities to the endpoint. Thus, the call chain looks like this:
Botkit App [calls Studio API] → Botkit Studio [sends message to the NLU service] → LUIS [resolves intent and entities] → Botkit Studio [finds convo object based on intent trigger and returns convo to the bot] → Botkit App [makes an API call from skill] → API [returns response to the bot] → Botkit App [sends response text to the chat client]
It makes me feel that I'm using it wrong. How do you use the new NLU feature for cases like this?
Thank you.
You can use LUIS directly as a middleware INSTEAD of or IN ADDITION to using the cloud. This can be useful if you wanted to say, only process content that does not result in a hear match to the NLP provider. The inbuilt LUIS support is designed for people that do no want to or are unable to code this kind of logic, and allows you to just work with Studio's trigger and console to help train the NLP provider.
You might want to check this out if you have not seen it, it takes you through how responses are evaluated in your studio application, and where you can manipulate that processing:
https://botkit.ai/docs/readme-pipeline.html
I want to use REST async client callback, meaning the server is causing a callback operation to be invoked on the client side when a response is ready (see Jersey's 'Asynchronous Services and Clients' to get what I mean)
Can I express this in Swagger/RAML/anything similar, and enjoy the relevant server/client code generation, documentation generation etc.? Can you point to relevant examples/resources?
OAS (formerly Swagger) considered it:
https://github.com/OAI/OpenAPI-Specification/issues/716
https://github.com/OAI/OpenAPI-Specification/issues/737
and even merged the callback feature and landed in OAS 3.0.
But the tools I used doesn't seems to support the addition at the moment.
Checkout out Async API
Quoting from https://www.asyncapi.com/v1/guide/
AsyncAPI provides a specification that allows you to define Message-Driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over MQTT, AMQP, WebSockets, STOMP, etc. The spec is very similar to OpenAPI/Swagger so, if you’re familiar with them, AsyncAPI should be easy for you.
Repo: https://github.com/asyncapi/asyncapi
Async API supports
Documentation Generation : https://www.asyncapi.com/v1/tooling/docgens.html
Code Generation (Java, Node.js): https://www.asyncapi.com/v1/tooling/codegens.html
There is also Swagger Callback feature ( documentation for the callback feature. )
That comes with OAS 3.0 as far as I remember. So there isn't a tool which supports this feature yet.
I am working on a project and I need to use this tow api; jtapi, gjtapi. The problem is
both gjtapi and jtapi project seem dead. Is there a new similar java api?
JTapi is a specification that is implemented by vendors, as CISCO or AVAYA. In my experience, there is no an generic API for JTapi, because each provider customizes their own implementation according at their telephony platform.
If you want a "generic" JTapi you should review this link, that refer to an Asterisk JTapi:
http://asterisk-jtapi.sourceforge.net/
OData protocol documentation (http://www.odata.org/documentation) describes two versions - 2 and 3.
What are the core differences between two versions?
Are both versions are supported by existing client libraries or version 2 is considered to be "legacy"?
To rephrase - are version 2 clients compatible with version 3?
There are lots of differences between the two versions. For example, OData v3 adds support for actions, functions, collection values, navigation properties on derived types, and stream properties. It also introduces a completely new serialization format for JSON ("application/json" means completely different things in the two versions).
When an OData client makes a request to a server, it can (and should) specify the maximum protocol version it can understand via the MaxDataServiceVersion HTTP header. A client written to only understand v2 of the protocol won't be able to understand a v3 payload.
I don't think I'd call v2 "legacy" or unsupported, but individual servers can choose whether or not to support requests that can only understand up to v2 (or v1). I think many existing clients out there support both v2 and v3. I know the WCF Data Services clients (desktop, windows phone, windows store, and silverlight) do support both.
In addition to a previous answer be aware that some client tools may still support only OData v2 protocol, so in case you need v3 specific features, you should make sure your client code is not limited by something like auto-generated proxy classes that are not capable of handling array types.
Here's an example when server exposes v3 features, but it's not possible to use them because Visual Studio WCF Data Service client proxy generator only supports v2:
http://bloggingabout.net/blogs/vagif/archive/2012/12/16/using-odata-protocol-v3-with-mongodata-odata-provider.aspx
You can find the list of all the differences between the two versions in the pdf of the Open Data Protocol (OData) Specification.
Specifically, the changelog is at section "1.7 Versioning and Capability Negotiation"