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.
Related
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.
I want to develop and application with the Oracle ADF, but I want a RESTful web service that will allow for other clients (a desktop app, a mobile app, etc...). TO help me determine the best way to do this I have two questions:
Does the ADF have some easy way to create a REST service built into the application?
If not, can I create a JAX-RS web service and hook it up in the same container as the ADF application?
I am thinking that because of what the ADF is, it may be best not to try to create a service with it. If so, please alert me of this.
Now with the release of jDeveloper 12.2.1 ADF comes with inbuilt REST Freamework which will solve all kinds of requirements(CRUD Operations, Custom method invocation, Paging, Data Consistency Check etc.)
The link for getting started with this
https://docs.oracle.com/middleware/1221/adf/develop/GUID-8F85F6FA-1A13-4111-BBDB-1195445CB630.htm#ADFFD589
will help a lot in getting started with REST and ADF.
For getting into more advanced features please follow this link
https://docs.oracle.com/middleware/1221/adf/develop/GUID-589F3905-5A8D-402D-B2D2-3BEEB2D7DDD4.htm#ADFFD54082
this will help in implementing all the other features in the ADF way.
Yes you can build and consume REST from ADF Faces, please see below a step-by-step tutorial for ADF 12c:
http://docs.oracle.com/cd/E53569_01/tutorials/tut_rest_ws/tut_rest_ws.html
This will work well for simple use cases, where there is not much complexity behind data entry screens.
However, you must keep in mind that ADF is most powerful when using Business Components and Bindings. Any other combination will decrease your productivity.
Yes, you can build REST service on top of ADF components, here's a fresh tutorial showing how to proceed with many Java technologies : http://multikoop.blogspot.com/2014/06/create-restful-services-on-top-of-adf.html and also http://waslleysouza.com.br/en/2014/10/expose-adf-bc-restful-web-service/
With JDeveloper 12.2.1 release, an easy way to create REST services has been provided. Using this feature, you can expose the entity objects of your choice as REST resources and then consume them easily via the DC palette.
Take a look at this blog which provides some insight into the same:
http://stick2code.blogspot.in/2015/11/creating-adfbc-rest-services-new.html
I am exploring OpenUI5 to use it as front end for developing SAP applications. One thing I noticed is that it is more user friendly with OData services/OData model. I believe, it may be a close initiative of Microsoft with SAP or vice-versa.
I am using Java technology along with JCo outside SAP environment. I am exploring for the best options.
Should I expose my Java services as OData services to leverage OpenUI5 capabilities?
1 I see that Java implementations for OData support is limited to Version 2 and Version 4 is underway. This community is very small, not surprisingly.
Should I limit the usage of OpenUI5 only for: application definitions, view definitions, layouts, etc. and use Java services (e.g. REST/SOAP)?
1 Here, I have to add my JavaScript/jQuery logic for the CRUD operations on UI controls. I am not sure how much of it is supported for plain JSON/XML objects if I push JSON/XML response from server.
Just to be clear, I hope you have a clear understanding of Odata and REST. The difference is that OData is a specific protocol; REST is architecture style and design pattern.
The OData protocol is built on top of the AtomPub protocol. The AtomPub protocol is one of the best examples of REST API design. So, in a sense you are right - the OData is just another REST API and each OData implementation is a REST-ful web service.
Odata is the way to go since with Odata Model & binding, the pain of writing a lot of javascript is reduced by a huge proportion.
I think you should keep it simple and use REST API and Json to communicate between your back end and SAPUI5 front end.
I've just started on a small project to create some REST services using Google App Engine and Java. I'm new to both technologies, but I've done some reading on both. I'm familiar with SOAP (have used them previously), and I think I understand the conceptual differences between REST and SOAP.
Currently I need info regarding two things:
1) I'm trying to find some tutorial which builds a simple REST service from scratch for deploying on Google App Engine (GAE). The simpler the better, but it should have at least a few routing options. I don't need any UI, if that matters.
2) Which RESTful Framework should I use with Google App Engine. Again, simplicity is what I'd like, and something which has tutorials and a newcomer can easily grasp.
My ultimate goal is to just write a REST wrapper with multiple routing options, which eventual consumes some pre-existing SOAP services and returns their results.
Have you checked out Google Cloud Endpoints for creating a REST service? Its pretty simple and straightforward, also has support for OAuth.
I would give Jello framework a try. It offers a clean, and simple to follow, JSON format and provides a very powerful and comprehensive RESTful implementation that follows the OData specification.
Here is Jello's REST development guide: http://jello-framework.com/guide/rest.html
I am involved with a team that uses Xcelsius for their dashboard presentation design. I know of options provided by SAP to connect to the database. My team used flynet but lisence issues are pushing us to think of custom webservice. Can design a custom webservice (C# or Java) and use it with Xcelsius. I will realy like to know if its worth it or there are better options for my team. thanks
I was recently involved with an engagement that built out custom web services to both write new and alter existing records in the database. This was the only option for us as SAP does not provide any viable options to write back out of the box. Also, I don't think they (SAP) should but this was a unique requirement that necessitated the workflow.
The web services were in .net