TL;DR

We're excited to roll out the first iteration of Downstream Calls in Micro! This feature lets you integrate custom logic into your APIs by defining acceptance criteria and executing code during request processing. It's the early stages, so while you can't import external modules just yet, and credential management is manual, we're actively developing enhancements, including dependency and secret management. Dive into the details below for how to define, write, and test your downstream code with our new editor. Stay tuned for updates that will fine-tune your experience and expand capabilities!

Introduction

Let me first explain what Downstream Calls are and why they are so important. Micro enables you to create APIs by defining what they need to do, using plain text or structured test cases, which we refer to as Use Cases. But what if you want to call another API, a database, or simply embed some specific logic in your API? Well, this is where Downstream Calls come into play.

Downstream vs Upstream Calls

In Micro, an Upstream Call is what sends requests to your API, while a Downstream Call is made by your API to access databases, other APIs, or custom logic. The terminology was chosen for clarity in our design, and it's best illustrated with a diagram:

Essentially, Downstream Calls are calls that are made by the API that is being defined in Micro. This is the instrument for the user to extend the functionality of the API beyond the generated code.

Downstream Calls Release

We're rolling out Downstream Calls to give you the power to execute your own code during API request processing. You'll find a new addition in the schema menu for defining these calls with a name, description, and the executable code. Just like crafting a request schema, you now craft the logic that runs behind it—empowering your API with extended functionality.

Unlike with the Upstream Schema, here you would define the interface of the function that will be executed during the request processing. But the principles are exactly the same, since what is an API if not just a function call over a network?

Code Editor

Downstream calls come with a dedicated code editor that allows you to write and test your code.

We have added an integrated code editor that allows you to write your code, with syntax highlighting and code completion. At this point (subject to change), you write code as if you are writing a body of a function.

• Input: You will always receive a parameter called request that will have a structure you define in the schema.
• Output: You need to return an object of a structure you define in the schema. If you defined more than one type of Response in the schema, you can return any of them.
• Errors: We urge you to handle all the errors gracefully and return them as defined in the schema. If there could be an error in your code, make sure you have defined it in the schema.

Code Testing

To uphold our commitment to Test-Driven Development (TDD), the new Downstream Call Editor includes comprehensive testing tools:

Ad-hoc Testing

Quickly test your code with any input. This flexible approach allows for rapid, on-the-fly validation of logic changes.

Regression Testing

Use your defined Use-Cases to validate individual Downstream Calls, ensuring your updates meet the specified criteria without affecting existing functionality.

Comprehensive reports offer insights into the input, output, and any errors, aiding in debugging and refining your code.

Collective Regression Testing

When multiple Downstream Calls are involved, this mode ensures they all work in harmony. It's essential for validating the overall functionality before launching a new API version.

Limitations

The debut of Downstream Calls focuses on core functionality, allowing the execution of custom code. Currently, it does not support external Node.js module imports, and handling credentials requires a manual process. We're fully aware these are vital features, and they are next in line for development.

NOTE: We're in active development to enhance Downstream Calls with dependency and secret management capabilities, anticipating changes to support a broader range of Node.js modules and secure credential handling.

Further Releases

Work is underway on Dependency Management and Secret Management features to elevate Downstream Calls to full production readiness. These updates will enable you to import any Node.js module and manage your secrets effortlessly.

Stay tuned and check out our upcoming blog post for an in-depth look at these exciting developments.