- May 13, 2015

Web APIs are exposing the state of your domain. Apart from trivial examples, those domains are rarely flat! It’s not just about one kind of entity with mere primitive properties, or entities with simple references to other entities. Instead, you’ll certainly have an entity with lists of properties, or more complex sub-components, and even lists of them. APISpark’s entity stores let you define composite properties, for your deeper model needs.

As a foodie, I’d like to store recipes and their ingredients in an entity store that will be exposed as a Web API in APISpark. For that, from the dashboard, I’ll start by creating an entity store to collect all my tasteful recipes!


In the overview section of our newly created store, we’ll create two entities: one for our ingredients, and one for our recipes.


In the entities panel on the left hand-side, you’ll be able to add properties to your entity. We’ll add a name of type String for that ingredient, but more interesting, we’ll start adding composite properties to represent the constituents of that ingredient.

We want to know how healthy our recipes will be, so we’ll track the constituents of the ingredients by noting the quantity of fat, proteins and carbohydrates. And for instance, there are different types of carbohydrates — that’s a hint towards the fact that you can nest composite properties!

But we can also track the various vitamins available too — thanks to lists! APISpark supports lists of primitive values, as well as list of references or composites.

On the recipes front, our recipes will also need to reference a list of ingredients.

Let’s see how we could model that, and it’s definitely not flat (and hopefully not too fat or sweet either)! Let’s have a look at our model:


As the screenshot shows, an ingredient has a “constituents” composite property, containing “lipids” and “proteins” properties, a list of strings representing “vitamins”, and there’s also a nested composite property with the “carbohydrates”. The recipe has an “ingredients” property which is a list of composites.

For brevity, I’ll skip the explanations on how you can export a Web API from an Entity Store, and we spoke recently about how you can directly try out your Web APIs from the built-in Swagger UI. But I’ll show you what it looks like when you’re issuing a GET /ingredients call on the API:


We have our “constituents” composite property, containing a nested composite property for the “carbohydrates”.

Similarly, if you do a GET /recipes with the built-in Swagger UI, to retrieve all the recipes:


Notice the list of ingredients, which contains ingredients consisting of a quantity, a unit optionally, and a reference to an ingredient.

Thanks to composite properties, APISpark lets you model your domain the way you imagined it!


  • Owen Rubel

    Thats not a bad idea. Perhaps Composite and CompositeList for clarity. Nice 🙂

    • Owen Rubel

      Actually no you are right. The outer parent is considered ‘List’ or ‘Array’ while what is contained is ‘Composite’. Still nice addition… mind if I implement? 🙂

      • Guillaume Laforge

        In the UI, we have a visual clue with the icon saying it’s a list.
        And when creating, we keep the same logic as for other fields, to stay coherent, which is to check / uncheck the checkbox to say if it’s a list of that type or not.

  • Pingback: This week in API land, 7th edition | Restlet - We Know About APIs()