Dragonfruit makes data accessible by parsing it into models and APIs and then serving those APIs.

[ data ] -> [ parser ] -> [specification] -> [ server ]

This allows you to take data that looks like this:

    {
        "fruitId":1234,
        "fruitType":"dragonfruit",
        "fruitColor":"red"
    }

and turn it into API endpoints you can query like this:

http://your.site/api/fruits?fruitType=dragonfruit&fruitColor=red

When you parse a piece of sample data, Dragonfruit will create several API endpoints.

Dragonfruit's API endpoints follow the pattern of /type/{id}/subtype/{sub_id}/subtype2/{subtype2_id}.... The root type and endpoint route is specified when the command line is run, while subtypes are named after the field in the sample data they come from.

For any given type of data, Dragonfruit will create a "collection" endpoint ending in a slash (/type/, /type/{id}/subtype/) for querying multiple items and creating new ones and a "single" endpoint (/type/{id}, /type/{id}/subtype/{sub_id}) for loading and manipulating single items.

If that sounds confusing, here's an example:

sample_data.json:

    {
        "id":123,
        "branch":[
             {
                "branchId":123
             }
        ]
    }

Command:

dragonfruit -type=tree -file=sample_data.json

Endpoints:

/trees/                           // Returns multiple Trees
/trees/{id}                       // Returns a single Tree with a specific ID
/trees/{id}/branches/             // Returns multiple Branches from a single tree
/trees/{id}/branches/{branchId}   // Returns a single Branch from a single tree

Dragonfruit uses HTTP verbs to distinguish the type of operation done on an endpoint. Dragonfruit uses the following semantics for operations on endpoints:

• GET - retrieve items
• POST - add a single new item
• PUT - replace/overwrite an existing item in its entirety
• PATCH - partially replace an existing item
• DELETE - delete an item

Dragonfruit creates standard operations for each endpoint. For "collection" endpoints (endpoints ending in a slash) Dragonfruit will create GET and POST operations. For "individual" endpoints, Dragonfruit will create GET, PUT, PATCH and DELETE operations. So, for the endpoints above:

"Collection" endpoints (ones not ending with an {id} parameter) are queryable using GET parameters. Typically any simple (non array) property can be queried (see Models and Queries for the specific queries you can do based on the sample data).

"Individual" endpoints (ending with an {id} parameter) can also be called via GET. An individual endpoint will only return a single item - the one with the corresponding ID.

New items can be added with POSTs to the appropriate collection API.

POST-ing the data

    {
        "fruitId":1234,
        "fruitType":"dragonfruit",
        "fruitColor":"red"
    }

to http://your.site/api/fruits will create an item that would then be retrievable by a GET operation.

Note: Dragonfruit doesn't currently normalize or resolve or reject duplicate IDs. It assumes your application is doing that.

PUT operations replace items in their entirety, PATCH options replace items partially.

For example, starting with an item like this:

    {
        "fruitId":1234,
        "fruitType":"dragonfruit",
        "fruitColor":"red"
    }

PATCH-ing this data:

    {
        "fruitColor":"green"
    }

would result in an item that looks like this:

    {
        "fruitId":1234,
        "fruitType":"dragonfruit",
        "fruitColor":"green"
    }

PUT-ing the same data would change the item to this:

    {
        "fruitColor":"green"
    }

You can delete an item by sending an HTTP DELETE request to the item's endpoint.