How do we document a message based API in Swagger or RAML ?
By message based I mean that the endpoint is always the same, but one can send multiple message types to this endpoint and depending on the type of input message we get different responses.
Is there an example of this type of API I can have look ?
Thank you.
Luis Oscar
Swagger and OAS is especially used to document REST-like APIs. After a long search I have found the AsyncAPI specification. This can be used to document your message driven APIs.
There´s also an online editor available and if you are already familiar with using swagger, yaml it is easy to get started with this specification
Related
Quick and simple: Is it possible to get the complete OAS/YAML/JSON definition of these APIs? For example the ESIGN API.
I want import these definitions and generate a connector to do a low/zero coding implementation.
Thanks in advance.
AA
Alejandro, you're in luck.
DocuSign uses the OpenAPI (OAI) Specification - formerly known as "Swagger" - to describe its REST APIs. The goal of the OAI specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service. For more info see the official OAI spec.
Following this question :
Microsoft Graph API mail office 365: Is any option create inbox message NOT as Draft?
I want to convert from EWS to Graph API ,
in EWS it is under the section below:
https://msdn.microsoft.com/en-us/library/ms527629.aspx
How can I change/ modify mail message flags with REST ?
I saw in beta version is possible somehow...
Part of the REST is here:
https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/mail_api_overview
Any suggestions please ?
#Nicolas is correct. Check out Microsoft Graph API mail office 365: Is any option create inbox message NOT as Draft?
In there there is a link to an MSDN article that explains each of the flags, their integer values, etc...
It's important to remember that while the graph API (for Exchange related foo) looks a lot different than EWS, they actually share a bunch of the same logic underneath and ultimately talk to the exchange Store underneath. What this means is that all of the MAPI goodness (proptags, named props, etc...) can be accessed through the graph API via extended props. Funny bit of trivia - currently the REST API on the server side when it deals with extended props converts them into the EWS internal representation of extended props and calls the server side EWS business logic (in proc) to process them. So not only is it similar, it is exactly the same :)
We need to get Bing Maps to one of our apps in Power Apps. Whenever we enter a URL of the format on Power Apps http://dev.virtualearth.net/REST/v1/Imagery/Map/imagerySet/centerPoint/zoomLevel?mapSize=mapSize&pushpin=pushpin&mapLayer=mapLayer&format=format&mapMetadata=mapMetadata&key=BingMapsKey, we get an error stating that the Swagger file cannot be found. We tried enter the URL by going to Connections->Manage Custom Connector-> Create Custom Connector->Use an OpenAPI Url
So far we've tried connecting several Bing Map API endpoints, we've read through the docs and are unable to find a Swagger definition file on Bing's API. Do we have to create our own Swagger for this API and is there a template we can follow?
Passing in the URL you provided won't work as it returns an error. You would need to pass in a URL that returns a response. That said, the response structure of Bing Maps REST services is very complicated and you would need to use several different requests to see the full response object. There is no single way to return the complete JSON structure of the REST services as they vary depending on which end point you use. The Bing Maps REST Service JSON schema is documented here: https://msdn.microsoft.com/en-us/library/jj870778.aspx
That said, if you are using .NET, take a look at the official .NET library for the Bing Maps REST services: https://github.com/Microsoft/BingMapsRESTToolkit/
This is my understanding:
Swagger is a notation/rules to write documentation. But why is it called a framework (like Angular/MVC)?
Swashbuckle is a program (JavaScript?) that generates the documentation (based on Swagger rules).
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Is this information correct? If not can someone explain in simple terms what Swagger, Swashbuckle, and Swashbuckle UI mean?
Also, what do I lose as an API developer if I do not use this?
Swagger is a notation/rules to write documentation. But why is it called a framework(Like angular/MVC)?
It is probably called a "framework" because its' purpose is to offer a systematic way of notating the interface of any RESTful service under the OpenAPI Specification. This is a big deal to developers because the spec is overseen by the Open API Initiative under the reputable Linux Foundation.
Swashbuckle is a program(javascript ?) that generates the documentation(based on Swagger rules)
Swashbuckle is more of a package (or a library) that you can make use of in your .NET Web API projects. It's purpose, as you have correctly indicated, is to generate the Swagger spec for your project. Additionally, the Swagger UI is contained within Swashbuckle so if you are developing an API in .NET it's really a nice one-stop shop of a package. It is almost entirely written in C#, not JavaScript.
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Yes, it does display the Swagger spec in a nice, human-friendly manner. However, Swashbuckle is not a necessary component for this. They are, aside from what I just said previously, completely mutually-exclusive.
Also what do I lose as an API developer, if I do not use this.
This is now entering into the realm of opinion but I'll try to be objective about it. I use Swashbuckle to assist in the creation of clients for my application APIs. After getting past the implementation learning curve (which wasn't much), this package has saved me quite a bit of time of writing the clients myself. Writing a web client is a trivial thing for small applications but enterprise-level applications have a tendency to keep growing and/or changing in complexity so it is nice to have the creation/updating of these clients completely automated.
In short, if you decide not to use it you must either resort on an alternative method of API client generation or write/update the clients yourself. If you are only developing the back end this may be completely pointless to you but it would certainly help whoever is responsible for creating the client apps that will consume your API services.
I hope these answers have been helpful. Cheers!
I'm calling a web service, and I'm suspecting its response is not according to its specification. I'm not a WSL specification expert, so I'd like to ask if someone knows a tool that can be used to perform a validation between a WSDL file and a sample XML response. Does anyone know a tool that can validate if a sample XML response is according to WSDL specification?
Also, if you know a tool which I can provide the WSDL file and it generates a sample XML response it would work too.
Thanks,
SOAP UI is the perfect tool for this. Create a Test Case and add 'schema compliance' assertion. This would validate whether the SOAP response is compliant with the WSDL specification or not.
Detailed instruction can be found here: https://www.soapui.org/soap-and-wsdl/validating-soap-services.html
Thanks,
Sandeep