3. Best Practices and Opinions

Best Practices and Opinions

When creating new APIs with Dragonfruit, you should typically use sample data that comes from and is structured like the real data you work with. Dragonfruit will generally be OK with whatever form your data is in, but it does have a few opinions about certain aspects of your data design.

Everything should have an ID

Dragonfruit requires that all items (and sub-items and sub-items of sub-items etc.) have an ID parameter that serves as the primary identifier for each item. When parsing sample data, Dragonfruit will try to detect the ID parameter at each level of your data.

Dragonfruit will attempt to detect any parameter that matches either a parameter named the literal string id or a pattern matching [something]Id. For example, Dragonfruit would identify the id and branchId datapoints in the data below:

    {
       "id": 1,
       "branches": [
           {
               "branchId": 1
           }
       ] 
    }

Conventionally, the ID of the top-level item is named id and the ID of sub-items are named [subItem_type]Id.

Within an item, it's best practice to name each distinct ID parameter with a distinct name.

Bad:

    {
       "id": 1,
       "branches": [
           {
               "id": 1
           }
       ] 
    }

Good:

    {
       "id": 1,
       "branches": [
           {
               "branchId": 1
           }
       ] 
    }

Keep Model Names Unique

Dragonfruit stores a single list of all models used by all the APIs within an instance. This includes models of all top-level items and sub-items. This means that you have to be a little careful when naming your items and sub-items in order to avoid collisions.

For example, imagine an API that serves a model called fruits, formatted like this:

    {
       "id": 1,
       "color": "red",
       "seeds:": "black",
       "leaves": "green"
    }

And another API that serves a model called trees that has a sub-element that references fruits:

    {
       "id": 1,
       "trunk": "tall",
       "bark:": "brown",
       "fruits": [
            {
                "fruitId":1,
                "displayName":"apple"
            }
       ]
    }

When parsing the trees model, the fruit sub-element would overwrite the original fruit model. Conventionally, we name sub-elements that reference other models with the suffix "reference:"

    {
       "id": 1,
       "trunk": "tall",
       "bark:": "brown",
       "fruitReferences": [
            {
                "fruitId":1,
                "displayName":"apple"
            }
       ]
    }