I am new to this API Blueprint tool. Can anyone explain me how to use this tool for capturing all my Restful web services API using API Blueprint like this (https://clever.com/developers/docs/explorer#endpoint_districts_districts)?
Any Help
I am afraid we do not really offer a tool to generate an APIBlueprint starting from real API calls.
The main reason behind this choice is, as said, we believe that documentation and API definition is the first step to design great APIs, and not the last one.
I hope this clarifies the point of view.
Related
I'm currently studying computing and it tackles about API. I keep reading this term 'APIs provide an interface for communicating software' but i'm not really sure what is an interface to API? May i ask for your help to explain it?
Not sure if i get your question right, but let me have a try:
So basically a simple architecture of building for example an app is splitting it up in front- and backend. For example, in a ToDo-List app there is a server-side software which manages all data and we have a Mobile App which shows the data to the user. The backend is an "abstract" program. I mean with that that you can't click buttons or something else. So, when you want to create a task in your frontend app you have to tell the backend (for example written in Java or Python) that you want to make this. For this you can use an API.
This is basically an Call of an Website. The backend recognizes is and loads data out of an database, manages it and displays it for example in JSON Format. This format is send to the website.
Look here: https://jsonplaceholder.typicode.com/todos/1
The app now is able to automatically get this data and manages it.
Obviously real APIs are much more complex. For example you have to authenticate, you can hand over parameters and so on. You have POST, GET, DELETE Methods.
But this is simply the basic concept of an API.
Look here to know how to create an API (for example in Java): https://spring.io/guides/gs/rest-service/
Look here to know how for example an Mobile App consumes the API (in JavaScript): https://www.taniarascia.com/how-to-connect-to-an-api-with-javascript/
I hope i could help you :)
Best regards
Sebastian
Here is a simple use case to illustrate my question : imagine a bank mobile app, the features to implement are:
List the beneficiaries
Do a payment
We have one micro-service to handle the payments "PaymentService" and one to deal with the beneficiaries "BeneficiaryService". Both have a documented contract with RAML or OpenAPI.
I think it's not a good idea to let the mobile app call the two micro-services independently: it would expose too much the internal structure of the information system and provide no abstraction and so no mitigation.
So, we need to build a "facade" API that expose the routes of "PaymentService" + "BeneficiaryService" to ease the integration. Let's call it "MyAwesomeMobileApp"
I assume "MyAwesomeMobileApp" can be achieved by writing code (i.e. via an ESB or a dedicated Spring app) or via an API Gateway by configuration.
The thing is how do you provide aggregated documentation to your customer (the people coding the mobile app frontend) ?
By aggregated documentation I mean, a documentation with a set of routes from "PaymentService" and from "BeneficiaryService". A sort of third contract made with a subset of each micro-services.
Thank you
If you're providing (requiring) a gateway API between the application and the other services (which seems like a good choice in your example), you provide documentation only for the gateway API endpoints as the services it consumes are not relevant to the mobile app developer.
The way your facade implements communication with any services behind it could well be different than the services themselves (for example: hiding a field that is for internal use or using different field names) and, as such, the contract even for the service-specific models could well be different.
So, document the facade/gateway API well (and independently) and be on your way. It should internally have brokers or some other separation between the endpoints it exposes and the specific requirements of the services it consumes that allows them to be independently updated without too-tight coupling.
If you are looking for a simple concatenation of the contracts or in other words a "unified" public documentation that contains endpoints from both API specification documents/contracts, then you can give APIMatic's merging feature a try.
A detailed step-by-step walkthrough can be found here: https://docs.apimatic.io/manage-apis/api-merging/#merging-two-api-specifications---a-basic-example . However, in brief, the steps for your scenario can be:
Structure your API contracts in a root directory like shown in an example below:
dir\
payments\
openapi.json
beneficiary\
main.raml
APIMATIC-META.json
Here openapi.json and main.raml can be your OpenAPI and RAML contracts respectively.
A minimalistic APIMATIC-META.json configuration file can look like this to enable merging:
{
"MergeConfiguration": {
"MergedApiName": "My title",
"MergeApis": true
}
}
ZIP the directory, upload it and import it into the APIMatic Dashboard (You will need to sign up first).
Preview your public documentation by doing Generate > Proceed > Preview API Portal. Publish/host it as required.
If you are looking to automate the process, APIMatic has an API too: https://www.apimatic.io/docs/api#/http
When searching in Yammer it uses an /api/v2/search endpoint like this:
https://www.yammer.com/api/v2/search/models?search=test&start=0&size=20&model_types=threads&_network=xxxxxxx&relevance=DEFAULT
Compared to the v1 search endpoint this returns more data. We need this data. And we successfully tested using this v2 endpoint.
Now the question: Is this v2 search endpoint safe to use? Is it "official"? Maybe somebody from Yammer reads along - on their Help page it says:
We encourage you to post all programming questions to StackOverflow
with a #yammer hashtag
So here we are. Any help is appreciated.
The Yammer v2 search API endpoint is not yet officially supported for third-party use. This is because we anticipate the need to make changes to it as we build it out. There are no plans to lock developers out of experimenting with the v2 search API. However, when developing any important functionality against this API, automated testing should be used to detect any unannounced breaking changes that we make while we continue to build it out.
In LUIS, we have text/synonym recommendation in the entity/phrase list generation. Do anyone have idea on the api that is used for the synonym recommendation. We wanted to integrate the cognitive service api to get the synonym of the input text in one of the client application but we could not get any relevant Microsoft service to attain this.
[I am unable to provide sample code because of the nature of the question]
Luis Text Analytics
TextAnaytics API
Thanks
Unfortunately, we don't have any API for synonym recommendation yet. You can request this as feature here.
First off let me state this is HOMEWORK for school. I am looking for general ideas and direction, not "this is exactly what to write". We did not really cover API's so I am trying to learn as I go.
I have been asked to design an API that can be used with Facebook, for things like posting on my feed or adding new friends. I have been doing tutorials online and most seem to have me add some "ruby gem" that has whatever websites methods and stuff. For example I did a Twilio.com demo that needed require 'twilio-ruby' and a twitter one that needed require 'twitter'. To my understanding, these are "gems" and not "API's" correct? That being said, is Koala an API or a simply a gem that contains the methods I need for writing an API (specifically for Facebook)? If I were to use Koala and it was an API, I feel that would sort of defeat the purpose of writing an API (just reusing their methods and such).
Any other ruby API Facebook help would be greatly appreciated!
Have a look at https://developers.facebook.com/docs/other-sdks Koala is listed as "other" SDK, meaning that it provides a wrapper around the low-level Facebook Graph API requests. So, no, it's not an own (web) API IMHO.
In a narrower interpretation, an API is just an "application programming interface". This would not necessarily have to deal with being accessible for example via a REST interface. I think it depends on the definition of API, respectively what you professor expects. If this is unclear, I'd check back with him/her.
Check
http://en.wikipedia.org/wiki/Api
http://en.wikipedia.org/wiki/Web_API
http://en.wikipedia.org/wiki/Representational_state_transfer