I work on developing API services that internally call multiple micro-services
I was looking for a tool that could help me map public facing APIs with the application's user interface (application is available as native android/ios and PWA)
We do use tools like Swagger and NewRelic for internally maintaining API related details and documentation. However, I was trying to look up any tool(preferably open-source) that could help me map the api calls with the user interface
For example:
A Homepage Screen for the app with multiple buttons. Each button makes a REST API call. These REST APIs internally call micro services.
I would like to have a UI based tool where I could show the Homepage screen for the app(a screenshot) and then write APIs endpoints and routes associated to each button.
The reason I am looking to do this is because I believe this will make new people on the team(and external stakeholders) easier to read and refer to the application flow and how it is tied to the REST APIs. This will also make impact analysis easier when making changes to certain services/APIs
Related
I have several services, each one exposed through REST API with ASP.NET Core Web API. I use Swashbuckle for ASP.NET Core tooling in order to automatically generate from my controllers and DTOs all the necessary documentation and visualize it in SwaggerUI. I found this tooling really great, with little annotations on my models and my controllers already provides many features out of the box, such as a UI client to try out the REST API endpoints.
But with this solution each service has its own dedicated SwaggerUI instance and therefore UI.
I would like to offer to my customers a wiki-like documentation with a navigation menu, where, for instance, they can browse sections regarding all the endpoints exposed by my services and have on each page the same features offered by SwaggerUI.
It can be achieved by creating my own web application but I was wondering whether an out of the box solution or some tool that might ease such integration already exists.
I tried Slate but I felt like I had to re-invent the wheel in order to automate at least the creation of the basic API documentation, namely controller definition, response definition and descriptions. Does anyone have any suggestion?
I faced this very issue recently working in a microservices architecture, you're absolutely right. There is not need to reinvent the wheel.
I really can't recommend redoc by Redocly enough in this case.
Have a look at the multiple-apis example.
We are in the process of designing a front-end application with Angular which will call a jBASE server through RESTful APIs. APIs are created from jBASE component called jAgent.
Does jAgent support creating and verifying JWTs?
If not, what is the best way to handle authentication/authorization for the Angular application?
If we need to use JWTs, do we have to use a authentication middleware application (.NET Core or node.js) for that?
Great question! At the moment there is no handler within jAgent and our recommendation is to implement this, and advanced web server/API gateway technology by way of other applications like HAproxy or Kong.
An expansion of jAgent functionality to include things like this is something we're still considering but keep in mind, the power of jBASE lies in its native interactions with the host OS. Since there is no virtual OS layer it can be easier to plug and play off the shelf things to fill in for additional functionality, which gives you the flexibility to bring your own tooling.
In summary:
Not at the moment
Using an off the shelf package to act as your API gateway
Subject to the package you choose
That relegates jAgent to management of the API layer as it exists on the PICK/jBASE side while the off the shelf package manages your API security layer.
One other note for you--I noticed that you included a link to the old jBASE docs hosted on HelpJuice. It's worth mentioning that we've migrated those docs to docs.zumasys.com. You'll find the docs there to be more up to date, and also completely open sourced--part of the migration included their move to a GitHub repo, where we're happy to take community contributions.
For reference, the article you mentioned is available at https://docs.zumasys.com/jbase/connectivity/jagent/introduction-to-jagent-rest-services/.
Update:
One of our engineers has a program that will use openssl to generate the tokens for you, which you can find at https://github.com/patrickp/wjwt.
You will need openssl installed on the machine and in the path.
The WJWT.TEST program shows the usage. The important piece is the SECRET.KEY which is your internal KEY you use to sign the payloads.
When a user first authenticates you create the token with SIGN. Claims are any items/fields you wish to save/store. Do NOT put sensitive data in here as it is viewable by anybody. The concept is we sign this with our key, give it back to the client. On future calls the client sends the token and we pull it and call the VERIFY function which basically re-signs the payload and validates the signatures match. This validates the payload was not manipulated.
Activities such as expiration you would build into your code.
Long term we plan to take this library and refactor the code into our MVDB Toolkit library with more functionality. That library is something we provide to jBASE customers at no additional charge.
I want to mock api calls from my application, and host the mock, so my tests can work without calls to real api. There is a service called restbird which does exactly that, but it is far from ideal for me. If you want to collaborate you have to host the service by your self. Also it has some errors like not displaying history of calls, or when it sends server errors for no reason. I want a service more robust than this one.
The only service that I think might be a good fit is SwaggerHub, it seems robust, it has virtual servers, and overall it is very popular. But the only problem is that I cannot find a way to record api calls from my application. So how can I record api calls for SwaggerHub?
There does not currently exist any functionality within SwaggerHub itself to record API calls made from the Swagger UI module within the tool. This is a limitation of the open-source Swagger UI tool.
What I can recommend is you use the Swagger Inspector tool. The Swagger Inspector can be used to make API calls from a client, save both the request and the response, and even generate an OpenAPI file for you based off the request/responses. If you create an account and sign in, you can even save your API calls to a collection to use later.
Swagger Inspector: https://inspector.swagger.io/builder
It may also be worth considering using ReadyAPI's Virtualization module to handle this use case. With ReadyAPI Virtualization you can record transactions from a browser, build mock services from the recorded transaction or an existing API definition, and then host the mock service using VirtServer.
ReadyAPI is a part of SmartBears API lifecycle products, so there are integrations between the two tools. For instance, you can port APIs from Swaggerhub into ReadyAPI directly and you can use mock services built in ReadyAPI to do dynamic mocking in Swaggerhub.
You can find more information about ReadyAPI Virtualization here: https://smartbear.com/product/ready-api/api-virtualization/
I realise this is a very late response to this thread, but hopefully this information comes in handy.
Let's suppose I was going to design a platform like Airbnb. They have a website as well as native apps on various mobile platforms.
I've been researching app design, and from what I've gathered, the most effective way to do this is to build an API for the back-end, like a REST API using something like node.js, and SQL or mongoDB. The font-end would then be developed natively on each platform which makes calls to the API endpoints to display and update data. This design sounds like it works great for mobile development, but what would be the best way to construct a website that uses the same API?
There are three approaches I can think of:
Use something completely client-side like AangularJS to create a single-page application front end which ties directly into the REST API back-end. This seems OK, but I don't really like the idea of a single-page application and would prefer a more traditional approach
Create a normal web application (in PHP, python, node.js, etc), but rather than tying the data to a typical back end like mySQL, it would basically act as an interface to the REST API. For example when you visit www.example.com/video/3 the server would then call the corresponding REST endpoint (ie api.example.com/video/3/show) and render the HTML for the user. This seems like kind of a messy approach, especially since most web frameworks are designed to work with a SQL backend.
Tie the web interface in directly in with the REST api. For example, The endpoint example.com/video/3/show can return both html or json depending on the HTTP headers. The advantage is that you can share most of your code, however the code would become more complex and you can't decouple your web interface from the API.
What is the best approach for this situation? Do you choose to completely decouple the web application from the REST API? If so, how do you elegantly interface between the two? Or do you choose to merge the REST API and web interface into one code base?
It's a usually a prefered way but one should have a good command of SPA.
Adds a redundant layer from performance perspective. You will basically make twice more requests all the time.
This might work with super simple UI, when it's just a matter of serializing your REST API result into different formats but I believe you want rich UI and going this way will be a nightmare from both implementation and maintainance perspective.
SUGGESTED SOLUTION:
Extract your core logic. Put it into a separate project/assembly and reuse it both in your REST API and UI. This way you will be able to reuse the business logic which is the same both for UI and REST API and keep the representation stuff separately which is different for UI and REST API.
Hope it helps!
Both the first and the second option seem reasonable to me, in the sense that there are certain advantages in decoupling the backend API from the clients (including your web site). For example, you could have dedicated teams per each project, if there's a bug on the web/api you'd only have to release that project, and not both.
Say you're going public with your API. If you're releasing a version that breaks backwards compatibility, with a decoupled web app you'd be able to detect that earlier (say staging environment, given you're developing both in-house). However, if they were tightly coupled they'd probably work just fine, and you'll find out you've broken the other clients only once you release in production.
I would say the first option is preferable one as a generic approach. SPA first load delay problem can be resolved with server side rendering technique.
For second option you will have to face scalability, cpu performance, user session(not on rest api of course because should be stateless), caching issues both on your rest api services and normal website node instances (maybe caching not in all the cases). In most of the cases this intermediate backend layer is just unnecessary, there is not any technical limitation for doing all the stuff in the recent versions of browsers.
The third option violates the separation of concerns, in your case presentational from data models/bussines logic.
in standard "page-based" webapps, it´s quite easy to implemet direct links to several pages, f.e, an url abc.com/app/customer/4711 which directs the user directly to the page diplaying customer 4711.
Is there a way to reproduce a similar behaviour in an GWT-App?
Tnk Mica
You can use Activities and Places design pattern. It provides easy access to any "place" within the app:
https://developers.google.com/web-toolkit/doc/latest/DevGuideMvpActivitiesAndPlaces
Every once in a while this question is being asked in one form or another and I think misconception exists about what GWT is best suited for.
GWT is an amazing set of tools for creating web applications: JavaScript multi-screen user interfaces which run in modern web browsers, load as a single web page and generally don't need full page reloads or page switching for their operation.
Navigation between screens happens in response to triggered events (for example, a user pressing a button, a timer firing or server-side state changing). The data needed to be presented is acquired asynchronously via XHRs (again without web page reloading).
GWT provides an elaborate framework for all of the above - Activities & Places for navigation, as Andrei mentioned, GWT-RPC and RequestFactory for data acquisition and exchange, and much much more to make advanced and highly-structured web apps which leverage the processing power of modern machines and capabilities of modern browsers.