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
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
I would like to access the adwords API through a simple single page web application using javascript. I would like to dynamically stop and start some of my adwords campaigns.
I can't seem to find any documentation on the REST endpoints for the API - only documentation for the various libraries.
Is it possible to do this through javascript only?
The current Adwords API is a SOAP-based interface, so there are no REST endpoints to use. It's of course still possible to construct SOAP messages and call operations without using one of the provided libraries.
Having said that, the next evolution of the API (the "Google Ads API") will support both gRPC and JSON REST-based communication, which would probably fit your scenario better. It's not yet ready for production use, however.
Around a year ago I made an iOS application that finds restaurants near your location of any type and displays information about them. I made a web service call using the FourSquare api to get all the data which was returned in json format and then I parsed it and displayed the information on the UI of the app. Now I want to make an android application using Xamarin.Android since I am learning working with Xamarin studios and C#. When I make a Xamarin.Android application and go to packages then add packages I see there is a Foursquare api package that has a .NET wrapper around it. Here is the website url:
https://www.nuget.org/packages/Foursquare.Api/
So my question is how does this work? Does adding this package mean I don't have to make a web serivce call anymore, instead all the data is stored inside this package and I just have to get all the data the same way I get information from a local database? What are the advantages of using this package instead of just making a web service call to Foursquare?
Think of it this way:
This Foursquare API is simply a .NET wrapper of the web service that you want to use. Thus, somebody has gone ahead and done all of the hard work for you so you can simply consume the returned data in your applications.
What does this mean for you?
Well it means that you don't have to write any REST consumption code and you can focus more on the actual application and any business logic that you need to implement based on the Foursquare objects.
To not confuse any further, this data would come the same way as if you wrote your own web service to access the data from the Foursquare API endpoint.
Advantages:
Already written for you
You don't need to know your way around their REST API
Usually follows best practices per language so it's easy to consume (Objects created, methods, etc)
Disadvantages:
REST endpoint might be updated and not reflect in the package until it's updated
Any bugs/issues in the framework can be hard to workaround if the project is not open source
Could be a lack of documentation on how to use the wrapper
I'm new to web API design, so I've tried to learn best practices of web API design using these articles:
1.Microsoft REST API Guidelines
2.Web API Design-Crafting Interfaces that Developers Love from "Apigee"
Apigee is recommending web API developers to use these recommendations to have better APIs.
I quote here two of the recommendations:
I need C# code for implementing these recommendations in my Web APIs (in ASP Core) which is a back-end for native mobile apps and AngularJs web site.
Sweep complexity behind the ‘?’
Most APIs have intricacies beyond the base level of a resource. Complexities can include many states that can be updated, changed, queried, as well as the attributes associated with
a resource.
Make it simple for developers to use the base URL by putting optional states and attributes behind the HTTP question mark. To get all red dogs running in the park:
GET /dogs?color=red&state=running&location=park
Partial response allows you to give developers just the information they need.
Take for example a request for a tweet on the Twitter API. You'll get much more than a typical twitter app often needs - including the name of person, the text of the tweet, a timestamp, how often the message was re-tweeted, and a lot of metadata.
Let's look at how several leading APIs handle giving developers just what they need in
responses, including Google who pioneered the idea of partial response.
LinkedIn
/people:(id,first-name,last-name,industry)
This request on a person returns the ID, first name, last name, and the industry.
LinkedIn does partial selection using this terse :(...) syntax which isn't self-evident.
Plus it's difficult for a developer to reverse engineer the meaning using a search engine.
Facebook
/joe.smith/friends?fields=id,name,picture
Google
?fields=title,media:group(media:thumbnail)
Google and Facebook have a similar approach, which works well.
They each have an optional parameter called fields after which you put the names of fieldsyou want to be returned.
As you see in this example, you can also put sub-objects in responses to pull in other information from additional resources.
Add optional fields in a comma-delimited list
The Google approach works extremely well.
Here's how to get just the information we need from our dogs API using this approach:
/dogs?fields=name,color,location
Now I need C# code that handles these kind of queries or even more complex like this:
api/books/?publisher=Jat&Writer=tom&location=LA?fields=title,ISBN?$orderBy=location desc,writerlimit=25&offset=50
So web API users will be able to send any kind of requests they want with different complexities, fields, ordering,... based on their needs.
Given an existing API working well with the usual mono-locale approach, what are the steps one should follow to turn it into an internationalized version, which enable user to send/receive keys/values in localized versions?
End user interface internationalization is a well covered topic.internationalized. But how can it be pushed further on request and response? If someone hits an API and wants the response in German how can I do so ?
It is kind of tricky answering without any kind of context, or sample API, or a even a high-level description of what your API does.
But in general it is best to separate your APIs into several layers.
The core functionality and data at the application level should be locale independent, something like this http://mihai-nita.net/2005/10/25/data-internationalization/
Then you would have the presentation layers, with things like date/time/number formatters, collation, localization, etc.