In order to understand what an orchestration layer does, take a look at the following image:

In simple words: an API Orchestration Layer (OL) is responsible for assembling different API responses
(ie. /product/123 and /product/123/reviews) at a single endpoint (ie. /view/web/product/123), so that a service
can make one single call to that endpoint and retrieve all the informations needed to render its views with
a single API call.

The advantage of this approach is that:

you can spread the workload over multiple, concurrent requests

you can have very clean, separate, decoupled, resource-oriented APIs on the background

If your applications uses different APIs to build user interfaces, you might want to invest on your own orchestra!
And in order for an orchestra to be succesfull, it needs a very good conductor.

There are 2 main concepts that you will have to understand before using the conductor:

resources: these are objects representing your resource-oriented APIs, that the conductor will call in order
to assemble its responses

facade: the endpoint of the conductor, a facade allows you to define which resources should be aggregated
there (and a few other, minor, things, like how the conductor should assemble the responses from the sub-requests it
makes)

and then you can simply run node yourFile.js: by default, the conductor will run on port 6971, but you can override
this setting by just specifying the port during the startup process (for example -p 8080).

Of course, the above example won't be very helpful since we are not telling the conductor on which routes it should
listen to, nor which facades to run for those routes; to do that, we simply have to 1. add some routes and 2. add facades
and configure them.

In order for our conductor to respond to a request hitting http://example.org/web/view/users/john, for example, we simply need
to add a new route (the router used by the conductor is odino.router):

conductor.router.load({

example:{

pattern:"/example.json",

facade:"f1"

}

});

In this way we are telling the conductor that for whichever request that hits /web/view/users/:username it will need
to run the user_detail facade. But how do we define what the facade does?

We can simply populate the conductor.config object with these informations:

conductor.config.resources ={

user_details:{

url:"http://api.example.org/users/:username"

},

user_friends:{

url:"http://api.example.org/users/:username/friends"

}

};

conductor.config.facades ={

'web_user_details':{

resources:[

'user_details',

'user_friends'

]

}

};

or, alternatively (recommended), dump the configuration in a more readable YML file and load it:

at that point, it will see that it needs to run the facade user_detail

the conductor will then look into its config, finding out that it needs to hit http://api.example.org/users/:username
and http://api.example.org/users/:username/friends, assembles the responses and serve them to the client

If you start the conductor in dev environment (--env dev or -e dev) you will get some additional informations
everytime you hit an endpoint, such as a list of resources and the body of each resource the conductor hit in order to
serve the response: