EDAF75 – API for Krusty 2025

The following snippet encodes and decodes a string in Python:

from urllib.parse import quote, unquote

title = "Änglar, finns dom?"
url_encoded_title = quote(title)
print(f"{title} is encoded as {url_encoded_title} ...")
url_decoded_title = unquote(url_encoded_title)
print(f"... and we can get {url_decoded_title} back")

The following snippet encodes and decodes a string using the Java standard library:

import java.net.URLEncoder;
import java.net.URLDecoder;

var title = "Änglar, finns dom?";
var urlEncodedTitle = URLEncoder.encode(title, "UTF-8");
System.out.printf("%s is encoded as %s ...\n", title, urlEncodedTitle);
var urlDecodedTitle = URLDecoder.decode(urlEncodedTitle, "UTF-8");
System.out.printf("... and we can get %s back\n", urlDecodedTitle);

A call to:

POST /reset

should remove all customers, recepies, ingredients, orders, and pallets from the database – this should never fail.

It returns:

• status: 205 (which is a recommendation for clients to update their view of the resource)

• body:

  { "location": "/" }
  

  This is a bit contrived, but after posts, we often want a link to the newly posted resource – in this case it's really the whole database, so we might as well return the 'root' path (/). Also, as noted above, REST services normally return this link in the response header, but to keep the project simple, we return it in the response body.

To add a new customer, we post to the /customers endpoint:

POST /customers

with the body:

{
    "name": "Bullar och bong",
    "address": "Bakgatan 4, Lund"
}

(see notes at the bottom of this page for information about how to send a JSON body when testing with curl).

This should give the following response:

• status: 201 (we've added a new resource)

• body:

  { "location": "/customers/Bullar%20och%20bong" }
  

  This is sent in the body of the response, so we could have returned the name 'Bullar och bong', but since it's supposed to be a link to the created resource, which will later be sent as a part of a URL, we want it URL encoded anyway.

To make things easier, we can assume that the client doesn't try to create a new customer with the same name as an old customer.

To see all customers, we use:

GET /customers

and we'll get:

• status: 200
• body:

{
    "data": [
        {
            "name": "Bullar och bong",
            "address": "Bakgatan 4, Lund"
        },
        {
            "name": "Café Ingalunda",
            "address": "Återvändsgränden 1, Kivik"
        },
        {
            "name": "Kakbak HB",
            "address": "Degkroken 8, Malmö"
        }
    ]
}

The names of the fields (name and address) must be exactly the same as above, but the indentation is free as long as it is valid JSON.

To inform the system of an ingredient we want to use in our recipes, we use:

POST /ingredients

and the body:

{
    "ingredient": "Bread crumbs",
    "unit": "g"
}

which returns:

• status: 201

• body:

  {"location": "/ingredients/Bread%20crumbs"}
  

Some ingredients will need URL encoding, so we use it for all ingredients – you can safely assume that no one tries to add an ingredient which is already in the database.

To update our current stock of an ingredient (after a delivery), we use:

POST /ingredients/Bread%20crumbs/deliveries

with the body

{
    "deliveryTime": "2024-03-05 10:30:00",
    "quantity" : 20000
}

which increases our stock of "Bread crumbs" with 20000 units (i.e., in this case grams).

An update should return:

• status: 201

• body:

  {
      "data": {
          "ingredient": "Bread crumbs",
          "quantity": 36000,
          "unit": "g"
      },
  }
  

  where "quantity" is the total quantity after the delivery.

To see all registered ingredients, and their current stock, we call:

GET /ingredients

It returns:

• status: 200

• body:

  {
      "data": [
          {
              "ingredient": "Chocolate",
              "quantity": 42000,
              "unit": "g"
          },
          {
              "ingredient": "Bread crumbs",
              "quantity": 36000,
              "unit": "g"
          },
      ]
  }
  

To add a cookie, we post to /cookies:

POST /cookies

and add the name and repice in the request body:

{
    "name": "Almond delight",
    "recipe": [
        {
            "ingredient": "Butter",
            "amount": 400
        },
        {
            "ingredient": "Sugar",
            "amount": 270
        },
        {
            "ingredient": "Chopped almonds",
            "amount": 279
        },
        {
            "ingredient": "Flour",
            "amount": 400
        },
        {
            "ingredient": "Cinnamon",
            "amount": 10
        }
    ]
}

The units for the ingredients are given when we define them using POST to /ingredients, so we don't need to give them here.

As above, we can assume that no one tries to add the same cookie several times (i.e., you don't have to check for name collisions) – and our test script will only use ingredients which have been added properly beforehand, so it's safe to assume that all ingredients are OK (but all bets are off when you test it yourself…).

The return values will be:

• status: 201 (since we assume it's a new cookie)

• body:

  {"location": "/cookies/Almond%20delight"}
  

We can list all our cookies with:

GET /cookies

which returns:

• status: 200

• body:

  {
      "data": [
          {
              "name": "Almond delight"
          },
          {
              "name": "Amneris"
          },
          {
              "name": "Berliner"
          },
          ...
      ]
  }
  

  This endpoint will be slightly modified below (see "Cookies, part II") – but for now, the output above suffices.

To see a specific recipe, we use the

GET /cookies/<cookie_name>/recipe

endpoint, so to see the recipe for "Almond delight", we send:

GET /cookies/Almond%20delight/recipe

It returns:

• status: 200 if the cookie exists, or 404 if there is no such cookie

• body: if the cookie exists, we return:

  {
      "data": [
          {
              "ingredient": "Butter",
              "amount": 400,
              "unit": "g"
          },
          {
              "ingredient": "Sugar",
              "amount": 270,
              "unit": "g"
          },
          {
              "ingredient": "Chopped almonds",
              "amount": 279,
              "unit": "g"
          },
          {
              "ingredient": "Flour",
              "amount": 400,
              "unit": "g"
          },
          {
              "ingredient": "Cinnamon",
              "amount": 10,
              "unit": "g"
          }
      ]
  }
  

  If there is no such cookie, we return an empty recipe:

  {
      "data": []
  }
  

When a pallet is about to be produced, we call:

POST /pallets

with the request body

{
    "cookie": "Tango"
}

This puts the new pallet in the store immediately (so the time stamp should be 'now'), but only if there are ingredients enough to bake the whole pallet. This should be checked by the database itself, using constraints and/or triggers, we don't want your client program (i.e., your Python or Java code) to handle ingredients.

The call returns:

• status: 201 if there are ingredients enough for one pallet, otherwise we return 422.

• body: if a pallet is produced, we want its 'location', such as:

  {"location": "/pallets/e02b15b7b3e4ac432669c6b0fa294692"}
  

  If no pallet is produced, we return

  {"location": ""}
  

To check all our pallets we call:

GET /pallets

with the following query parameters (we can use any combination of them, or none):

• cookie: the name of the cookie
• after: only show pallets produced after (not including) the given date
• before: only show pallets produced before (not including) the given date

So, to check all pallets with "Almond delight", baked before "2024-03-02", we run:

GET /pallets\?cookie=Almond%20delight\&before=2024-03-02

and get:

• status: 200

• body:

  {
      "data": [
          {
              "id": "e515eb06a8cb417256f7c8736fa8bec4",
              "cookie": "Almond delight",
              "productionDate": "2024-03-01",
              "blocked": 0
          },
          {
              "id": "c03b044998a9092bc44527fcd65d5cf1",
              "cookie": "Almond delight",
              "productionDate": "2024-02-28",
              "blocked": 0
          },
          ...
      ]
  }
  

  Note that we only want pallets which are still in our store (but in this version of our service, we have no way to mark a pallet for delivery – see the section "Beyond this project" below if you want to try it out). We'll come to the "blocked" field below, but when a pallet is blocked, it has the value of blocked set to 1, otherwise it is 0.

To block or unblock pallets with a given cookie, we use

POST /cookies/<cookie_name>/block

or

POST /cookies/<cookie_name>/unblock

with the potential query parameters (we can use any combination of them, or none):

• after: only block pallets baked after (not including) a given date
• before: only block pallets baked before (not including) a given date

So, to block all pallets of "Tango" baked in the last week of February, we call:

POST /cookies/Tango/block\?after=2024-02-21\&before=2024-03-01

and to unblock all pallets of "Almond delight" we call:

POST /cookies/Almond%20delight/unblock

The call should return

• status: 205 (clients may want to update their views)
• body: an empty string

Above, we wanted the call:

GET /cookies

to return only the names of the cookies, but now that we've introduced endpoints for pallets, we want the output of GET on /cookies to show the number of unblocked pallets we have with the cookie in store:

• status: 200

• body:

  {
      "data": [
          {
              "name": "Almond delight",
              "pallets": 2
          },
          {
              "name": "Amneris",
              "pallets": 0
          },
          {
              "name": "Berliner",
              "pallets": 10
          },
          ...
      ]
  }
  

This means that you must modify the code which handled GET on /cookies, you should not add a new endpoint for this!

Observe that we have 0 pallets of "Amneris" in the example above – all cookies should be present here, even if we have no unblocked pallets of them in store!

We create a new order using:

POST /orders

with the body:

{
    "customer": "Bullar och bong",
    "deliveryDate": "2024-03-16",
    "cookies": [
        {
            "cookie": "Almond delight",
            "count": 3
        },
        {
            "cookie": "Tango",
            "count": 1
        }
    ]
}

It returns:

• status: 404 if either the company or any of the cookies doesn't exist, otherwise 201

• body: if the order is correct (201 above), we return:

  {"location": "/orders/f0430cff188d6a340a7df2557898b561"}
  

  Here, "f0430cff188d6a340a7df2557898b561" is the order-id.

  I anything is wrong with the order (i.e., we return the status code 404), we return an empty string.

You can then try to come up with endpoints for:

• Showing the orders of a given customer (probably under /customers/...)
• Checking how many pallets of each cookie we must bake before a given date (given how many orders we have for it, and how many pallets with it are already in store)