My talk at Percona Live 2015

The slides of my talk at Percona Live 2015 (Amsterdam) are online. It was titled “MongoDB and REST APIs a Match Made in Heaven” and it was meant as an introduction to Mongo, REST principles and the Eve python framework.

Overall it has been a pleasant experience, although I found that splitting 300 attendees through seven concurrent tracks ultimately led to too much fragmentation. People often found themselves with 2-3 interesting talks all happening simultaneously, and just had to pick one.

I could only stay one day so I missed all side events, speakers dinner included, which was a bummer.

Building custom endpoint handlers with Eve

On Stack Overflow and the Eve mailing list, but also in my mailbox and even on Twitter, I get a lot of enquiries on how to build custom endpoints within a Eve-powered RESTful application. Now, since within Eve all endpoints are fully customizable, what they really mean is:

How do I setup endpoints without any binding to a data entity, just connected to a custom method?

They would like to call something like /mycustomendpoint and get the response from a method they have defined somewhere in the Python sources. The standard endpoint-entity mapping provided by Eve covers 90% of their needs, but sometimes they just need endpoints that have nothing to do with data entities.

This is very easy to achieve. I’m writing it down so I can point people to this post in the future.

Eve is Flask

Eve is a Flask application and I really mean it since it is, in fact, a Flask subclass. Eve adds out-of-the-box RESTful capabilities to the Flask micro-framework. Most of the time you will be happy with just Eve’s own features but remember, the full Flask (and Werkzeug at a lower level) features set is also part of your arsenal.

Whatever you can do with Flask, you can do with Eve

So yes, of course you can easily set some functions to be invoked when a custom endpoint is hit with a request. The following snippet is a slightly modified version of Flask’s very own Quickstart tutorial:

from eve import Eve
app = Eve()

def hello_world():
    return 'Hello World!'

if __name__ == '__main__':

By decorating the hello_world method with the route decorator we added a new endpoint to the application. Each time a request to /hello comes in, it will be routed to our custom method. Of course the regular API endpoints (either defined in, passed as a dict at launch, or registered live by calling the register_resource method) will also be available.

Say that you saved the above snippet as and also have your RESTful endpoints properly configured. Launch the script:

$ python
* Running on (Press CTRL+C ...)

You can now point your browser to http://localhost:5000/hello/ and enjoy the application greeting. Or you can consume any other configured API endpoint.

As all of Flask features are at your fingertips you might as well opt for registering a blueprint, which is what the awesome Eve-Docs extension is doing in order to provide a static HTML /docs endpoint on top of any Eve powered API.

FatturaElettronicaPA for .NET has been updated

FatturaElettronicaPA has just been updated to v0.1.4. With this release invoice bodies (FatturaElettronicaBody items) are also validated. As always, you can install the package directly from NuGet. See the original post for more info. Also don’t forget to check the related projects.

Update: v0.1.6 has also been released.

Cerberus 0.9 has been released

A few days ago Cerberus 0.9 was released. It includes a bunch of new cool features, let’s browse through some of them.

Collection rules

First up is the new set of anyof, allof, noneof and oneof validation rules. anyof allows you to list multiple sets of rules to validate against. The field will be considered valid if it validates against one set in the list. For example, to verify that a property is a number between 0 and 10 or 100 and 110, you could do the following:

>>> schema = {
...     'prop1': {
...         'type': 'number',
...         'anyof': [
...             {'min': 0, 'max': 10}, 
...             {'min': 100, 'max': 110}
...         ]
...     }
... }

>>> doc = {'prop1': 5}
>>> v.validate(document, schema)

>>> doc = {'prop1': 105}
>>> v.validate(document, schema)

>>> doc = {'prop1': 55}
>>> v.validate(document, schema)

allof is the same as anyof, except that all rule collections in the list must validate. Same pattern applies to noneof (no rule in collection must validate) and oneof (only one rule in collection must validate).

Type coercion

Type coercion allows you to apply a callable to a value before any other validators run. The return value of the callable replaces the new value in the document. This can be used to convert values or sanitize data before it is validated.

>>> v = Validator({'amount': {'type': 'integer'}})
>>> v.validate({'amount': '1'})

>>> v = Validator({
...     'amount': {
...         'type': 'integer', 
...         'coerce': int
...     }
... })
>>> v.validate({'amount': '1'})
>>> v.document
{'amount': 1}

>>> to_bool = lambda v: v.lower() in ['true', '1']
>>> v = Validator({
...     'flag': {
...         'type': 'boolean', 
...         'coerce': to_bool
...     }
... })
>>> v.validate({'flag': 'true'})

>>> v.document
{'flag': True}

Properties (keys) validation

propertyschema is the counterpart to valueschema (also new, it replaces the now deprecated keyschema) and validates the keys of a dictionary.

>>> schema = 'a_dict': {
...     'type': 'dict', 
...     'propertyschema': {
...         'type': 'string', 
...         'regex': '[a-z]+'
...     }
... }

>>> document = {'a_dict': {'key': 'value'}}
>>> v.validate(document, schema)

>>> document = {'a_dict': {'KEY': 'value'}}
>>> v.validate(document, schema)

List of types

The type rule can now be a list of types, to allow for different type of values for the field.

>>> v = Validator({
...     'quotes': {
...         'type': ['string', 'list']
...     }
... })

>>> v.validate({'quotes': 'Hello world!'})

>>> v.validate({'quotes': ['Do not disturb my circles!', 
...                        'Heureka!']})

>>> v = Validator({
...     'quotes': {
...         'type': ['string', 'list'], 
...         'schema': {'type': 'string'}
...     }
... })

>>> v.validate({'quotes': 'Hello world!'})

>>> v.validate({'quotes': [1, 'Heureka!']})

>>> v.errors
{'quotes': {0: 'must be of string type'}}

And there is more so make sure you check the changelog before upgrading. No breaking changes but there’s at least one deprecation, as mentioned.

Fun fact: Cerberus is currently getting 3x the downloads of his sister project Eve, the REST API Framework for which the tool was originally conceived. Interesting if you consider that Eve is featuring 10x the GitHub stars. Fun, but not really surprising since Cerberus probably has a broader audience.

Special thanks to Frank Sachsenheim, Tobias Betz, Brett and C.D. Clark III for their valuable contributions to this release.

If you want to get in touch, I am @nicolaiarocci on Twitter.

Monolith vs Microservices

I spent the last couple days in Paris with a bunch of smart architects and developers who are about to deal with a complex Monolithic-to-Microservices architecture transition.

On my flight back to Italy I jotted down a few thoughts on the topic and then, this morning, the first thing that comes up on my newsfeed is Monolith First by Martin Fowler. Stunning, because the essay content totally resonates with my own notes, so much that it would perfectly serve as a recap for them.

Going directly to a microservices architecture is risky, so consider building a monolithic system first. Split to microservices when, and if, you need it.

And also, perhaps more importantly:

A more common approach is to start with a monolith and gradually peel off microservices at the edges. Such an approach can leave a substantial monolith at the heart of the microservices architecture, but with most new development occurring in the microservices while the monolith is relatively quiescent.

I find it fascinating that there is a chance that my notes and the essay were written (by astral coincidence?) in the very same minutes.

Composition vs. Inheritance: How to Choose?

Steven Lowe piece on Composition vs. Inheritance is a must read. Just to wet your appetite, let me quote the opening paragraph:

In the beginning, there was no inheritance and no composition, only code. And the code was unwieldy, repetitive, blocky, unhappy, verbose, and tired. Copy and Paste were the primary mechanisms of code reuse. Procedures and functions were rare, newfangled gadgets viewed with suspicion. Calling a procedure was expensive! Separating pieces of code from the main logic caused confusion! It was a Dark Time.

Fattura Elettronica Open Source: Web Service PA

this post is about an all-Italian open source release, so it’s going to be in Italian

Il progetto Fattura Elettronica Open Source si è arricchito di un nuovo strumento: Web Services. Il namespace FatturaElettronicaPA.WebServices raccoglie una serie di client C# che consentono di consultare i Web Service per la Fattura Elettronica messi a disposizione dalla Pubblica Amministrazione.

Sono disegnati in maniera da esporre tutti la stessa interfaccia ed essere al tempo stesso semplici e leggeri. Al momento lavorano in modalità sincrona ma l’obiettivo è di renderli tutti asincroni.

Come usare i Web Service

Prendiamo per esempio il Web Service che consente di convalidare un Codice Univoco di Fatturazione e recuperare le informazioni relative all’ufficio:

var ws = new CodiceUnivocoFatturazioneWebService()

// Authorization Id ricevuto dall'ente.
ws.AuthId = "<auth Id>";
// Codice univoco dell'ufficio che ci interessa
ws.CodiceUfficio = "KN3VNW";

if (ws.Ufficio == null) return;

// "Ravenna"

Molto semplice. Gli altri WebService (sono sette in tutto) operano secondo lo stesso schema. Ricordo che per l’utilizzo dei Web Services della Pubblica Amministrazione è necessario richiedere una specifica autorizzazione. L’Authorization Id è gratuito ed il rilascio è immediato, ma bisogna compilare un apposito questionario.


FatturaElettronicaPA.WebServices è su NuGet quindi tutto quel che serve è eseguire:

PM> Install-Package FatturaElettronicaPA.WebServices

dalla Package Console, oppure usare il comando equivalente in Visual Studio.

La libreria è una portable class library e gira senza modifiche sui seguenti ambienti: .NET Framework 4.0 e superiori; Xamarin.iOS; Xamarin.Android; Windows Phone 8; Windows Store apps (Windows 8); Silverlight 5.0. Enjoy!

If you want to get in touch, I am @nicolaiarocci on Twitter.

On my trip to Microsoft Build 2015

Last week I was in San Francisco for Build 2015, the annual conference event held by Microsoft and aimed toward software and web developers. Overall it has been a great experience. I especially enjoyed the opportunity to speak with Microsoft executives, Program Managers and developers about the new stuff they are cooking up and, in general, about that New Microsoft we all have been experiencing as of late (I have a guest post on MSDN Italy on that topic).

In this week TecHeroes episode I am interviewed along with my buddy Matteo Collina. At about 1m 20s in the episode Matteo and I share a few considerations on Open Source projects and technologies that really caught our attention at the conference, and of course on Microsoft in general. It is all in Italian by the way.