Creating edges

After creating the API, you can continue with creating your first edge.

An API Edge consists of a data model for a specific model provider and a collection of operations. There are default operations available on every edge, which you can customize, and you can create also create your own operations.

The default operations are the following:

• Get an entry: Returns an entry from the data provider which has the specified ID.
• List entries: Returns a list of entries from the data provider based on the specified filters.
• Create an entry: Creates a new entry in the data provider based on the specified model data.
• Replace an entry: Replaces an existing entry in the data provider which has the specified ID based on the specified model data.
• Edit an entry: Updates an existing entry in the data provider which has the specified ID based on the specified model data.
• Remove an entry: Removes an existing entry from the data provider which has the specified ID.

Models with relations have additional default operations, whose will be described in the next chapter.

1. Choosing your provider

An API can be built from data models using multiple data providers. So you have to specify the data provider for each API Edge you build. This can be done by implementing the API Edge Definition interface. You can implement it yourself for your own data source, but most times you can use an existing implementation called a model provider.

This time you will use the Mongoose Model Provider, which allows you to create API Edges for MongoDB collections:

 $ npm install --save api-model-mongoose

2. Creating your edge

To create you first edge, you must create a new file in the edges directory:

const { MongooseModelFactory } = require("api-model-mongoose")

module.exports = MongooseModelFactory.createModel("entry", "entries",
    {
        name: {
            type: String,
            required: true,
            unique: true
        },
        value: String
    }
)

The factory method has five parameters:

1. The singular name of the model
2. The plural name of the model
3. The Mongoose Schema definition for the MongoDB collection
4. The API Edge Schema definition (optional)
5. The name of the id field (optional, by default, it is "id")

3. API Edge Schema

Regardless which provider you use, you will always need an API Edge Schema. This specifies which model fields will be available via your API. If all fields are available and you don't need to rename any of them, then the edge schema will be generated by the model provider for you.

If you need to provide one, here are the rules:

• Providing "=" for a field means it's public
• Adding text after the = sign, connects the internal name of the field to the public name (eg. the internal _id becomes id in the public model)
• Excluding a model field makes it private

An example, renaming _id to id and making value private:

{
    id: "=_id",
    name: "="
}

You can also provide advanced transformations in the schema, but this topic is not covered in the Getting started section.

Now, you have an API edge, so we can continue with relations.