WasteSaver Audit: Orders GET endpoint

waste-saver-get-orders-v2.md

WasteSaver Audit: Orders endpoint

OLD ENDPOINT: GET /api/store/locations/:org_location_id/orders

NEW ENDPOINT (remains the same): GET /api/store/locations/:org_location_id/orders Payload proposal:

{
  "items": [
    {
      "reference": "17241405128753672",
      "date": "2022-08-24",
      "size_display": "20L",
      "quantity": 1,
      "type": 1,
      "scheduled_type": 2,
      "status": "deleted | temporary | new | pending | scheduled | in_progress | completed | delayed | cancelled | issue | in_review",
      "waste_stream": {
        "name": {
          "fr-fr": "PMD",
          "de-de": "Verpackungen",
          "nl-nl": "PMD",
          "en-gb": "PMD"
        }
      },
      "pickup_point": {
        "name": "Pickup Point",
        "address": {
          "street_name": "Keizersgracht",
          "house_number": "359",
          "postal_code": "1016 EJ",
          "town": "Amsterdam",
          "country_code": "NL",
          "lat": 52.3687078,
          "lon": 4.8849146
        }
      },
      "is_cancellable": true,
      "is_issue_creatable": true,
      "created_at": "2022-10-19 12:52:46.682394",
      "updated_at": "2022-10-19 12:52:46.682394"
    }
  ],
  "pagination": {
    "next": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "previous": null,
    "first": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "last": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "total_pages": 2,
    "total_items": 18
  }
}

A couple of points that should be more clear in this proposal:

• This is a collection and it should be paginated. Therefore, it is important to be very explicit on how the endpoint will be returning data.
• Pay attention to name consistency (e.g. the proposal for the new waste-stream-configurations endpoint is using waste_stream to wrap name and potentially other attributes. We might want to use the same name to describe this field).
• date is not a boolean, but rather a string with the following format YYYY-MM-DD
• By default, created_at and updated_at should be included in the new payloads
• pickup_point_id is not enough to ensure that you have all the necessary information to render that particular record.

Based on that, the suggested updated proposal is:

{
  "items": [
    {
      "reference": "17241405128753672",
      "date": "2022-08-24",
      "size_display": "20L",
      "quantity": 1,
      "type": "pickup | placement | rent | purchase | pickup_container | dropoff",
      "scheduled_type": "single | weekly | every_two_weeks | every_three_weeks | every_four_weeks | every_six_weeks | every_twelve_weeks",
      "status": "new | pending | scheduled | in_progress | completed | delayed | cancelled | issue | in_review",
      "waste_stream": {
        "name": {
          "fr-fr": "PMD",
          "de-de": "Verpackungen",
          "nl-nl": "PMD",
          "en-gb": "PMD"
        }
      },
      "pickup_point": {
        "name": "Pickup Point",
        "address": {
          "street_name": "Keizersgracht",
          "house_number": "359",
          "postal_code": "1016 EJ",
          "town": "Amsterdam",
          "country_code": "NL",
          "lat": 52.3687078,
          "lon": 4.8849146
        }
      },
      "is_cancellable": true,
      "is_issue_creatable": true,
      "created_at": "2022-10-19 12:52:46.682394",
      "updated_at": "2022-10-19 12:52:46.682394"
    }
  ],
  "pagination": {
    "next": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "previous": null,
    "first": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "last": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "total_pages": 2,
    "total_items": 18
  }
}

A couple of points that should be more clear in this proposal:

• This is a collection and it should be paginated. Therefore, it is important to be very explicit on how the endpoint will be returning data.
• Pay attention to name consistency (e.g. the proposal for the new waste-stream-configurations endpoint is using waste_stream to wrap name and potentially other attributes. We might want to use the same name to describe this field.
• date is not a boolean, but rather a string with the following format YYYY-MM-DD
• By default, created_at and updated_at should be included in the new payloads
• pickup_point_id is not enough to ensure that you have all the necessary information to render that particular record.

Based on that, the suggested updated proposal is:

{
  "items": [
    {
      "reference": "17241405128753672",
      "date": "2022-08-24",
      "size_display": "20L",
      "quantity": 1,
      "type": 1,
      "scheduled_type": 2,
      "status": "deleted | temporary | new | pending | scheduled | in_progress | completed | delayed | cancelled | issue | in_review",
      "waste_stream": {
        "name": {
          "fr-fr": "PMD",
          "de-de": "Verpackungen",
          "nl-nl": "PMD",
          "en-gb": "PMD"
        }
      },
      "pickup_point": {
        "name": "Pickup Point",
        "address": {
          "street_name": "Keizersgracht",
          "house_number": "359",
          "postal_code": "1016 EJ",
          "town": "Amsterdam",
          "country_code": "NL",
          "lat": 52.3687078,
          "lon": 4.8849146
        }
      },
      "is_cancellable": true,
      "is_issue_creatable": true,
      "created_at": "2022-10-19 12:52:46.682394",
      "updated_at": "2022-10-19 12:52:46.682394"
    }
  ],
  "pagination": {
    "next": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "previous": null,
    "first": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "last": "/api/store/locations/0804795f-fbff-46f7-bd60-0ba0cd30d409/...",
    "total_pages": 2,
    "total_items": 18
  }
}

Other than the status that I think it should be a number, I agreed with everything. Will update the gist with this 🙌