Customers API definition

c#-lambda-queries.json

{
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      // use a filter based on a C# lambda expression
      // https://www.strathweb.com/2018/01/easy-way-to-create-a-c-lambda-expression-from-a-string-with-roslyn/
      "query": "customer => customer.id == {customer-id}"
    },
    {
      "action": "add"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "customer => customer.id == {customer-id}"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "customer => customer.id == {customer-id}"
    }
  ]
}

customers-api.json

// Models a CRUD API for an entity
// Data is held in memory and is seeded from the specified JSON file
// which must return an array. The array can be empty if you don't want
// an initial set of items.
// All actions are optional and you define only those that you want to use
{
  // common URL part for all operations that belong to one entity so that we don't needto repeat it
  // you'll call this URL from your app and Dev Proxy will intercept it
  "baseUrl": "https://api.contoso.com/v1/customers",
  // JSON file with data
  "dataFile": "customers-data.json",
  "actions": {
    // get all items of the given entity type
    // returns all contents of the JSON file
    "getAll": {
      "method": "GET"
    },
    // get one specific item by its unique ID
    "getOne": {
      "method": "GET",
      // URL that's added to the baseURL defined earlier
      // {customer-id} is a parameter that'll be extracted from the URL
      // could be as well ?cid={customer-id}
      "url": "/{customer-id}",
      // JMESPath query that's used to find the requested item in the data file
      // uses values from URL parameters to lookup in the file
      "query": "[?id==`{customer-id}`]",
      "responses": {
        // this setup is default so we might've skipped it
        "ok": {
          "status": 200,
          "body": "@entity"
        },
        "notFound": {
          "status": 404,
          "body": {
            "error": {
              "message": "Customer not found"
            }
          }
        }
      }
    },
    "add": {
      "method": "POST",
      "responses": {
        "ok": {
          "status": 201,
          // return the newly created entity
          // (basically whatever was submitted in the request body)
          "body": "@entity"
        }
      }
    },
    "update": {
      "method": "PATCH",
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]",
      "responses": {
         "ok": {
          "status": 204
          // no body, means no response body, which matches the 204 status code
         },
         "notFound": {
          "status": 404,
          "body": {
            "error": {
              "message": "Customer not found"
            }
          }
        }
      }
    },
    "delete": {
      "method": "DELETE",
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]",
      "responses": {
         "ok": {
          "status": 204
         },
         "notFound": {
          "status": 404,
          "body": {
            "error": {
              "message": "Customer not found"
            }
          }
        }
      }
    }
  }
}

minimal-customer-api.json

// same API but with sane defaults
// we only define what's truly custom
// we use standad ok and notFound responses for all actions
{
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "actions": {
    // we define that we want to use an action but with all defaults
    "getAll": {},
    "getOne": {
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]"
    },
    "add": {},
    "update": {
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]"
    },
    "delete": {
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]"
    }
  }
}

multiple-actions-api.json

// allow multiple actions of the same type
{
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]"
    },
    {
      "action": "add"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "[?id==`{customer-id}`]"
    }
  ]
}