Server API v2 - What’s new?

I’d like to continue writing about new features of the Fn Project. This time I will tell you more about what is going on with Fn Project development and why you should keep an eye on it constantly.

Say goodbye to v1!

As a team, we are committed to delivering a high-quality open source project. We spend a year since our first announcement on making Fn the best open source FaaS platform. So, what is this all about? Today, we will look at some important underlying changes related to the Fn Server API… The Fn Server API v1 (aka “v1”) is no more! The Fn Server API v1 was all about a very common use case, i.e. write some code and “make it serverless”.

Routes

In v1, both functions and triggers were combined into a single entity called “route”. But “routes” had to go away, because with “routes” we already implemented an HTTP triggers API, despite the fact that a “route” was a combination of a function and its HTTP trigger path.

Anyway, “routes” are gone, forever. Hooray!

Asynchronous functions

With the Fn Server API v1 developers were able to invoke a function in an asynchronous manner. So, when you call a function you would get a “call ID” that may be used to track the function’s execution lifecycle using the v1 Calls/Logs API.

Despite the useful execution model, the way Async functions were implemented in v1 didn’t really scale. That is why it was decided to eliminate this type of execution in favour of a new v2 Triggers API. So as of now (November 2018) Fn doesn’t support async calls. The good news is that we are working on an improved solution with the same capabilities and same UX (okay, maybe a better UX too!).

Logs API

The v1 Logs API became the v2 Logs API, almost without any change! Internally Fn uses a “key-value store S3-compatible API” that allows developers to retrieve function logs after the function execution using the app reference (app name or ID) and the call ID. But not for long as the v1/v2 Logs API will soon be removed. As a replacement, we now recommend using the SysLog feature that Fn offers with the v2 Apps API. This feature allows Fn to stream functions logs to a remote syslog server (Logstash, Papertrail, Linux Syslog, … see here for more details).

Function format

With the v1 API, Fn allowed developers to configure the format of the request framing that is going to be shipped to a function (func.yaml’s format entry). We then realised that this type of configuration tends to confuse most of Fn users. From a developer perspective, there is no difference if the function uses an HTTP, JSON or a CloudEvent format because protocol interaction is hidden by the FDK (Function Development Kit). So, with certain changes done to the contract between Fn and a function, there’s no point to keep “format” around. http-stream is now the only supported format. And given that there is only one format, it will now be fully hidden.

Say hello to v2!

One of the goals of the Fn Server API v2 (aka v2) was to cope with all the deprecations mentioned above (routes, format, …) but v2 also brings important enhancements such as the ability for Fn to scale better. The Swagger API spec is a key asset to learn more about the Fn Server API v2.

Functions and Triggers

“Routes” are gone! As mentioned above, a “route” was a combination of a function and an HTTP webhook path. So, the first major change done in v2 was to split these two entities and introduce two distinct APIs: the Triggers API and the Functions API.

So, how does it work? The workflow remains almost identical. In order to create a function, you need to create an application; with an application ID and function ID, you can create a trigger.

Key changes being done to a function model

With the v1 API, Fn required certain parameters to create a “route”. In v2, we simply extracted all attributes that were actually related to an HTTP path. This is how a function definition now looks like in v2:

As you can see, path and type no longer belong to a function.

Trigger model

In v1, path and type were basicaly how the function could be triggered; type was in charge of an execution model definition. In v2, the meaning of type has changed, now it’s a trigger type. As of today, Fn supports only one type of trigger; i.e. http. With an HTTP trigger assigned to a function, Fn will provide an HTTP endpoint to invoque that function.

Unix sockets instead of STDIN/STDOUT

As you may know (or not), Fn was using STDIN and STDOUT as a transport for writing and reading responses from a function (the Docker API provides the interface to interact with the container). We are about to deprecate this STDIN/STDOUT approach in favour of UNIX sockets.

Previously, FDK listened on STDIN for an incoming request, then the parsing was performed, the data coercing was done, etc. We found out that this type of approach does not really scale. In addition, each FDK had to manually do the protocol framing for both the request and the response.

So, how does it works now? With Unix sockets, an FDK starts the web server on top of the Unix file socket transport, on the other side, Fn starts a container with socket file mounted. So, all the Fn server has to do is to forward the request (with some changes applied to it) from its own transport to a container socket transport.

Why it’s better? Well, FDK no longer needs to do manual protocol framing, each FDK uses native programming language proven tools that are widely used. The good news is that this change is transparent for developers using an FDK.

Syslog

As mentioned above, the v2 Logs API will be deprecated soon. As a replacement for that, v2 lets developers set the syslog endpoint using v2 Apps API. As we are building a service, we don’t need the maintain yet another store for user logs on purpose as well as an API on top of that that gives an access to log store, instead of that, we’d like developers to care about their logs by themselves that actually eliminates a middle layer between a user and function’s logs.

Fn CLI

All v2 changes have been integrated into the Fn CLI so please make sure to use a recent version. And regardless of that, it’s always a good idea to use an up-to-date version of the Fn CLI as we are constantly improving Fn.

v1 to v2 migration

In order to make the v1 to v2 transition smooth, we implemented the migration strategy that ended up being a part of Fn CLI — fn migrate. Just point the CLI on a function’s directory and see magic happening. Please note that not all features will still work when you migrate your function to v2 (see all the changes above).

• Take a look at the existing FDKs.
• Subscribe to the Fn YouTube channel.
• To learn more about the Fn, please visit the project home page.

Finally, join the Fn Army on Slack!