API Design for Low-Code Development - A Glimpse into Next ‘Best Practices’

As the low-code app platform movement converges with traditions of using APIs for  integration and access backend data, enterprises are looking for new best practices to bridge existing and new API capabilities.   Oracle’s Shay Shmeltzer and Robert Wunderlich share with IDN keen ideas worth consideration.

by Shay Shmeltzer, Director of Product Management – Oracle Cloud Development Tools - and - Robert Wunderlich, Product Strategy Director – Oracle Cloud Integration and APIs

Tags: APIs, integration, low-code, metadata, Oracle, REST,

Shay Shmeltzer, Oracle
Shay Shmeltzer
director of product management
Oracle Cloud Development Tools


"While some of the low-code tools support other sources of information, REST services will give you the biggest bang for the buck."

Application Architecture Summit
Modern Application Development for Digital Business Success
Online Conference

With the growing popularity of low-code platforms, backend service developers are facing increased demand for data access through APIs. In most cases the users of low-code development tools might not be experts in data access, and are relying on the backend developers to help them create better performing applications.

 

As the low-code app platform movement converges with well-established traditions of using APIs to access backend data, many developers and IT professionals are looking for new best practices, such as:

  • How should we design APIs that will be useful for those low-code platforms?
  • How would these low code-friendly APIs defer from those used for system-to-system integrations?

In this article, we’ll share some of the lessons we learned building and consuming APIs at Oracle for our own low-code development platforms.

 

Give Your Users a REST (API)

What technology should you use for the API you provide to your users.

Frankly, the answer today is obvious; it should be a REST API.

While some of the low-code tools might still support other sources of information such as SOAP services or even direct programmatic APIs in specific languages, all the modern tools support consuming REST services – these will give you the “biggest bang for the buck”.

 

REST services are simpler, lighter, and their stateless nature also reduces the load on your backend systems compared to older formats. This is why they are so popular--and not just for low-code platforms.

 

Tell Them What’s in the Box

REST services do have one downside, however, especially for declarative consumption – they don’t have built-in meta-data that describes their structure. While this might be ok when you are doing system to system integration where the consumption is quite static and can be pre-decided between the publisher and the consumer, in low-code situations this is challenging.

 

For a tool to consume a service without the need to code, meta-data is critical. It will tell the tool which fields are available, what their format is, which restrictions are applied to them (mandatory/unique etc.), which relationships exist between objects, and potentially many other pieces of information that can help a low-code tool create better mapping out-of-the-box.

 

There are a variety of meta-data formats for REST that aim to resolve such problems from the old OData standard which has often been replaced with Swagger and RAML. Now those formats are being replaced with OpenAPI and API Blueprint.

 

The challenge is that there is no single established de-facto standard similar to what WSDL was in the SOAP era. Many developers enjoy the freedom of not being burdened by heavy-weight description languages but often run into challenges with APIs that are not discoverable. This problem is magnified as low-code platforms attempt to provide guidance and auto-generation of configurations without proper visibility into the APIs in a format the platform can understand.

 

Until a clear leader rises, here is our choice for the best option:

Find out what is the metadata format preferred by your low-code platform and provide that format. If you have time to provide meta-data in more than one format – go for it.

Additionally, beyond the programmatic metadata (that will help the tool consume the service), don’t forget the human readable metadata better known as “documentation”. With so many APIs popping up the consumer can find it challenging to locate the specific API they need. Good documentation and potentially a searchable API catalog can ease this pain.

 

Simplify Your Structure

Here is another important ‘best practice’ step to help your apps and users consume your data.

Simplify where possible the data structure that consumers are going to get.

For example, if your data is coming from a relational database, you are likely dealing with a normalized data structure where many fields in the core Employee table refer to a code that resides in another table (job codes, location codes, department codes etc.).

 

While you could expose each individual code table through an API, it would be much more helpful if you flatten the structure of the data so that with one call the consuming app could get all the data they need including the translation of all the codes.

 

This means that rather than basing your API on a generic “select from one table”, you should look at queries that join the data from multiple tables and provide them as one cohesive record.

 

Not only will such structure simplify data access, it will also improve your application performance. More on that in our next tip.

 

Watch the Traffic

Here is another key best practice, one that we at Oracle actually learned through the school of hard knocks.

Minimize network traffic when and where possible. Expand the way you look for and detect such traffic.

That sounds like an obvious principal of good app design, but in the age of APIs, network traffic jams can be lurking everywhere. Double check how your low-code apps interplay with the APIs in the outside world and vice versa.

 

Let me share a “war story” from within Oracle to illustrate the point. 

 

One of our Oracle teams had recently complained about their mobile app taking too long to load the first page. They suspected that it was an issue with the development framework they were using, and were contemplating switching to another framework, but a deeper investigation revealed that this single screen was executing 18 separate calls to various APIs on the server. This meant that no matter what framework they would have used to build the application, the performance wouldn’t have improved. The fatal flaw was in the design.

 

This means that to minimize network traffic you’ll have to expand your arsenal.  Here are three (3) guiding principle we’ve found effective.

 

1. It might mean bundling data coming from several sources of data into a single REST call.

 

After all, the backend servers usually have better performance and are co-located with the data servers, making them much more efficient at handling data manipulations. This is especially true for mobile apps that might operate over slower networks. This is one reason that many mobile apps rely on a mobile backend service (MBaaS) to shape and construct mobile optimized APIs collecting data from multiple other APIs at the backend.

 

2. Don’t send over every attribute of the object that you have in store to the client. Send just what is needed.

 

For example, if your employee table keeps track of 100 fields of information on each employee – it is likely that not all of them are needed for the “employee finder” mobile app. You probably just need the employee name, title, and phone. This is an opportunity to create a dedicated API with just basic info for your consumers to access.

 

3.  Proper support for pagination on both the backend and front end can help ease the pain.

 

Improving performance doesn’t stop just with the structure of the data returned, but can also go into the number of rows returned. This is especially important for APIs that can return hundreds of records. Pagination is an important feature to support on the backend API. While the UI can limit the display of records to the top 20, it won’t help performance if, at the back, we still shuttled 2000 rows to the client.

 

Leverage Collaborative API Design

Using the right design platform brings your team together to collaborate on the design, accelerating the development of your solutions while reducing risk. As your front-end developer provides requirements of the API, your service developer is plugged in at the very beginning using a common design language. This common design language should promote communication and understanding at all levels of human users.

 

Using a design-first approach with collaboration, all participants should be able to test their designs as early as possible to catch flaws in their design. For example, without collaborative design, a service developer may spend quite a bit of time and end up just opening a basket of highly reusable services, but this may not be what the front-end developer needs.

 

By using a collaborative API design approach, teams can begin to see flaws in their design early. If the collaborative API design platform provides a mocking service from the design, the teams can test their designs and catch some of runtime issues before even investing in the implementation. The key here is to find and resolve problems as early as possible.

 

If this team mentioned in our “18 REST calls” Oracle war story were using a collaborative API design platform, they would have very quickly realized the flaw and could have corrected it before investing in implementation. The design team would have realized that they need to have a proper back-end platform to orchestrate the REST service calls and to surface it as a well-designed API.

 

Conclusion

Creating REST backend APIs today is easy. Many tools today would allow you to expose your data as REST services with a click of a button. But, for a truly useful API it is worth investing a bit more time thinking, designing, and documenting the APIs you provide. At the end of the day it will make both your consumers and yourself happy.

 

 

Robert Wunderlich (@WunderlichRd) is Product Strategy Director for Cloud, API, and Integration at Oracle, where he focuses on Microservices, and API Management.  He also regularly serves as a speaker for user group and partner community conferences in the U.S and Europe

Shay Shmeltzer is Director of Product Management for Oracle's Cloud Development Tools. He is focused on helping developers leverage Oracle's solution to simplify and streamline their daily work. His blog appears at blog at blogs.oracle.com/shay and on Twitter at @JDevShay.




back