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.
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
I have a bot that uses .NET, MS Bot Framework and LUIS.ai for its smarts.
All's fine, except that I need to provide a way for non-technical users to train the bot and teach it new things, i.e. new intents in LUIS.ai.
In other words, suppose that right now the bot can answer messages like "hey bot where can i get coffee" and "where can I buy some clothes" with simple phrases containing directions. Non-technical users need to be able to train it to answer "where can I get some food" too.
Here's what I have considered:
Continuing to use LUIS.ai. Doesn't work because LUIS.ai doesn't have an API. The best it has is the GUI to refine existing intents, and the upload app/phrase list feature. The process can be semi-automated if the JSON file with the app can be generated by some application that I write; however, there still needs to be backend code that handles the new intents, and that has to be implemented by a C# coder.
Could it work if I switch from C# to Node.js? Then theoretically I would be able to auto-generate code files / intent handlers.
Azure Bot Service. Seems it doesn't have a non-technical interface and is just a browser-based IDE.
Ditching Bot Framework entirely and using third-party tools such as motion.ai. Doesn't work because there's no "intellect" as the one provided by LUIS.ai.
Using Form Flow that's part of Bot Framework. If my GUI bot builder application can generate JSON files, these files can be used by Bot Framework to build a bot automatically. Doesn't work because there's no intellect as in LUIS.ai.
Keep using Bot Framework, but ditch LUIS and build a separate web service based on a node.js language processing library for determining intents. May or may not work, may be less smart than LUIS, and could be an overkill.
Override the method in LuisDialog that selects the intent from the LuisResponse, in order to use the my own way to decide the intent (but how?).
At this point I'm out of ideas and any pointers will be greatly appreciated.
First of all, LUIS.ai provides an API that you can use to automatize the training. Moreover, here is Luis Trainer written entirely in Python against the API that just does that.
The easiest one, probably is the one you are describing in #1: you can automatize the training (as explaining above) but you will still have to deploy a new version of the bot if new intents are being provided. One thing is letting users to train an existing model with new utteraces and another completely and different thing is to let them create the model :)
It might be hard to skip having to write the backend code (I wouldn't automatize that at all)
Here is a potential idea (not sure if it will work though). You would need 2 Luis models.
One with your current model, that users will be able to train with new utterances.
The second model, is one exclusively intended to be "expanded" with new intents by users.
If you separate this in that way, you might be able to look into a "plugin" architecture for the second LUIS model. So, your app, somehow, loads dinamically an assembly where the second model lives.
Once you you have that in place, you can focus on writing the backend code for your second Luis Model without having to worry about the bot/first model. You should be able to replace the assembly with the second Luis Model and be able in the bot to detect if there is new version of that assembly and replace the current one in the app domain.
As I said, is just an idea as I'm brainstorming with you. Sounds a bit complex, and it's not addressing all your concerns; as you still will need to write code (which in any case, you will eventually have to do)
I am working through a challenge project (training) to automate the creation of Chat Bots specifically targeted against a Luis.ai model using plain old javascript and web services to Luis.
I looked at the Bot Framework and it's just too cumbersome to automate (I want X number of customers to create a Chat Bot without coding). I also want to add my own type of 'Cards' (html widgets) that do more and can be easily configured by someone with zero coding skills.
Calls to the Luis.ai/Cognitive Services API are made in my code behind and the json response returned to my own rules engine. On the following URL click the LUIS API link on the page to open the Luis API Console where you can test, and train your Model. All the endpoints you will need are here...
https://dev.projectoxford.ai/docs/services/
Based on the various endpoints on that page, you can use WebClient in asp.net to pull back the response. So in my testing I have buttons on a page to push utterances up to the model, pull back entities, create hierarchical entities and so on. Have a look at http://onlinebotbuilder.com to see how an intent of product dynamically inserted a shopping cart.
When your tool is built and utterances start to arrive, Luis.ai will store them and via the Suggest tab (at Luis.ai) it will ask you for guidance...Unfortunately I don't think you could give that control over to your customers, unless they are experts in your domain (they understand which utterance belongs to which intent). You don't need to take your app down, just train it periodically to improve the Model based on your customers input...soon enough you will have your model working well based on your intents.
Hope that helps.
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.
So, I'm starting out building a social network web app. I'm looking into how to fit the parts of my stack together and I'm looking for some guidance about what various frameworks will allow me to do. My current stack idea is to have:
Firebase JSON API: serving user, post, comment, and all the other data
EmberFire: to plug that API into EmberJS
EmberJS: my front-end MVC (because I'm new to MVC and Ember seems the most accessible)
What I'm stumbling on at the moment is how I'm going to implement users with this stack. I've looked at basic authentication stuff but I haven't found anything that would allow me to allow certain actions and views for certain users and not others - the basics of a social network really.
Is it sensible to be doing this stuff in front-end MVC? If so what should I be using to do authentication/personalisation? If not, should I just be doing a PHP/SQL setup? I'd rather avoid that because my skills are all front-end.
If you are just getting started, Firebase is a great service to learn on due to their 'back end as a service' model - you will spend more time building/modeling your data and less time running/installing. Not that you won't want to learn more about that later, but it lets you focus on one piece at a time.
From an access perspective, JS/NoSQL vs PHP/MySQL isn't going to be the issue. They each have their own security requirements - it's more that PHP/MySQL has had more time to establish those rules. Additionally, Firebase being a hosted service has it's own set of requirements.
Firebase security rules are a little weird when you first look at them, but they begin to make some sense after you sit with them for a bit. The Firebase docs are actually a pretty great resource. https://www.firebase.com/docs/security/
Basically, if you use a Firebase 'login provider' it makes Firebase act as both a database and a authentication manager, and the combo helps keep users 'fenced' to where you want them. You can use data from other paths, variables, validation rules, etc. You can even make a 'custom login provider' if you need to integrate with an existing one.
Finally, on the client end, your view can respond to whatever Firebase returns - if a user does 'hack' their way through to a page they shouldn't be on client side, no data is returned anyways and no submitted information would be allowed because of the rules.