Source code here: https://github.com/azurestandard/beehive/blob/master/apps/api/views/stop.py#L646-L678

Landed in the API via https://github.com/azurestandard/beehive/pull/4916.

Need to document:

• drop (drop object, returned only if inline=drop is passed and the stop is a drop)
• pickup (pickup object, returned only if inline=pickup is passed and the stop is a pickup)
• dropId (int) (always returned if stop is a drop)
• pickupId (int) (always returned if stop is a pickup)

Landed in the API via https://github.com/azurestandard/beehive/pull/4788.

The website will need to display the lowest price as described in website issue #225. In order to do that we should include this in the packaged-product so that it does not need to be computed client side.

Everyone please feel free to update this (add other options I didn't find, add more pros and cons to existing options, etc, etc). And of course feel free to comment here with further thoughts and such.

Goals for consideration:

• Ability to update API spec (e.g. add, modify, and delete endpoints), possibly without having to edit raw YAML
• Add/enforce/support a process for collaborating on API-spec changes (e.g. PR reviews and approvals)
• Auto-generated documentation (for referencing endpoints outside of a YAML file)

Options:

SwaggerHub (link)

Price by month: $75/month if billed yearly, $90/month if billed monthly (up to 5 users)
Price by year: $900 if billed yearly, $1,080 if billed monthly

We initially went this route. A few key things gave reason to zoom out and consider other options.

Cons:

• Numerous bugs in their UI
• Being super under-impressed in their interface's overall UX
• Spec updates require editing raw YAML
• Needing their "enterprise" version (i.e. likely much more expensive than the plan we were on) for things as simple as pulling changes from the remote repository where the spec lives

Conclusion: Do not use. Surprised anyone would use it over the alternatives.

Postman (link)

Price breakdown: $12/user/month if billed yearly, $15/user/month if billed monthly
Price by month: $60 if yearly, $75 if monthly
Price by year: $720 if yearly, $900 if monthly

Pros:

• Has an in-app review process (for proposing and reviewing changes, similar to GitHub's PR UI with reviews).

Cons:

• Complex interface. For example, the have the concept of "collections" and "APIs". An API has collections, but collections can exist outside of an API. If wanting to update spec data in a collection, there's UI for it (no need to edit raw YAML). If wanting to update spec data at the API level (which includes the entire spec file) it's necessary to edit raw YAML.

Conclusion: Could be a decent route but the learning curve is steep. Seems it was first a simple HTTP client that added on team features that they could charge for (since the app itself is free, there's a strong business case for this type of move).

Stoplight (link)

Price: Free plan for up to 10 users. This seems like it would meet our needs.

Pros:

• Has a UI for making spec changes (but also supports editing raw YAML)

Cons:

• None found so far

Conclusion:

If the primary goal is an interface for updating the API spec without having to directly edit YAML then Stoplight.io seems like the only option (and their editor seems to be very nice and have an overall top-notch UX). That would keep the review process here in GitHub via PRs, which means that using Stoplight's UI would be 100% optional. There's currently a way to easily push to a new branch from Stoplight, but not to create a PR directly from it (see https://roadmap.stoplight.io/c/75-create-a-pull-request-from-studio). Reviewing PRs would still happen in GitHub, looking at the YAML, but there's also a way to view the updated docs (not a diff, so not sure how useful this would be) (see https://meta.stoplight.io/docs/platform/3.-design/c.reviewing-your-api-design.md).

Redoc/Redocly (github link | hosted service)

An open-source tool for generated a docs site from an OpenAPI spec. Generates very nice documentation sites (view demo).

Github: https://github.com/Redocly/redoc
Hosted service (with free plan that may be sufficient): https://redoc.ly/reference-docs

Beyond just documentation, their hosted service has a feature called "Workflows" that could be exactly what we're looking for. I still need to look into this a bit to fully evaluate whether it would meet all of our needs. Link: https://redoc.ly/workflows/

After testing out the "Workflow" feature of their hosted service, I learned that it will not meet our editing-related needs. It's essentially a type of "Netlify for api-spec documentation sites," where it can auto rebuild our docs site on merge of a PR. Since this functionality is fairly straightforward to replicate with Netlify, I don't see any benefit over using Redocly's hosted service for it (this is especially true for us because we have our api spec in its own repo).

Conclusion:

Redocly seems to be the way to go for a solid documentation site. We could use their open source package to generate the site statically and host it on Netlify.

See these sections in the website spec: 13.6.3 and 8.4.2.

Implement an API for Affiliate Referral Retrieval

Notes from our call:

/affiliate-referrals?person=123456

"affiliate-referral": {
    "created": '2018-08-10',
    "name": "Full Name",
    "amount-earned": 25.00,
}

order by date-referred desc by default

Landed in the API via https://github.com/azurestandard/beehive/pull/4738.

This is for moving a drop from one route to another.

It's being used here in the Logistics app.

Is this officially supported?
http://demo-beehive.azurestandardtech.com:8000/api/packaged-product-tags?internal=false&category=characteristic

I didn't see it in the spec but it works and I want to use it for Shopping Filters.

Spec out the API for managing notes on a trip level.

see azurestandard/website#482

There may be an issue with swagger in that swagger does not allow for requiring one of a list of properties.

The dropMembership model needs to indicate if it is still awaiting approval from customer service. This is part of the spec:

A status of pending needs to be placed on the customer’s drop membership association with the ability for a customer service representative to change that flag to approved. When this feature gets added into beehive we can set all existing drop members as approved (pending false) to start with. Any new member added to a drop is set as approved except if they come from the website as described here on a semi-open drop. Prospective members can retrieve information on a drop’s location, drop id and future stops, and they can place orders on those stops. Otherwise, prospective members should have the same access to drop data as non-members. The idea is that in most cases, customer-service will be able to get prospective members approved as full members by cutoff time, so we don’t want to hold-up order placement. But we also don’t want to leak private information to un-approved customers.

This can be done by either adding a 'pending' boolean property or possibly a 'status' enum string property if there is the potential for other status (besides 'pending' and 'active') to be used in the future.

The purchase endpoint needs to return the weight and temp for the driver application. Getting the temperature data is an expensive operation so it should only be included in the json response if needed as an inline "temperature" value. The weight can be included with the main object. The temp is a combination of dry_chill, frozen and greenhouse so I think an object like this

temperature {
  dry_chill: true,
  frozen: false,
  greenhouse: true
}

or and array with the different temps listed out like

temperature ["dry_chill", "greenhouse"]

would work.

@igregson What would your preference be?

Landed in the API via https://github.com/azurestandard/beehive/pull/4928.

Need to add isActive (boolean) and isDrivable (boolean) properties to the route endpoints.

This should show up in slack #general and not #github-communication

To go with https://github.com/azurestandard/beehive/issues/1065.

Allow the country of origin to be returned via the API.

See Website Issue #478

Reported upstream as swagger-api/swagger-ui#721. Until that's fixed, we should stick to internal $refs.

In discussions with @davidcross and @davidmcatee-azure about improving our SEO standings we would like the ability to store an SEO Title for a category. This new field would then be used by the website for our HTML Title tag.

This seo-name should be added to the /products endpoint.

The following tasks will need to be completed in the following order:

1. API Spec needs to be updated - This issue
2. Backend work - Beehive #3031
3. Website will need to consume the data - Website #1739

Background

Trips can have multiple trucks (PickSets). At this point the API has no way of knowing what truck is delivering for a stop. The DriverApp could use this info so that a driver is only working with their stops and not a list of stops that could be delivered on other trucks. In addition the logistics application could also benefit from the ability to group by truck as well

Note: While we are not adding driver info specific to each truck that is something we want to consider for the future. Right now the driver info is stored at the route level. It should really be at the pickset level.

Option 1

Trip Endpoint

• On the trip endpoint add a truckIds property as an array. The array would be PickSet id's that are available in the given trip.
• This array would be undefined if the trip is not yet verified as trucks are not setup until verification time.

Stop Endpoint

• Allow the stop endpoint to be filtered by truckId.
• On the stop endpoint add a truckId and truckNumber property as integers.
• These properties would be undefined if the trip is not yet verified.

Option 2

Trip Endpoint

• On the trip endpoint add a truckIds property as an array. The array would be PickSet id's that are available in the given trip.
• This array would be undefined if the trip is not yet verified as trucks are not setup until verification time.

Stop Endpoint

• Allow the stop endpoint to be filtered by truckId.
• On the stop endpoint add a truck object. Within that object have a property for id and number as integers. Then as we add driverName and driverPhone in the future it would also appear in this object.
• The truck object would be undefined if the trip is not yet verified.

It looks like FAQs are now on healthy-living, and the last /faqs hit I see in the logs is from a few weeks ago:

root@BH-PW:/etc/nginx# zgrep 'GET /faqs' /var/log/nginx/api.azurestandard.com.access.log*gz | tail -n1
/var/log/nginx/api.azurestandard.com.access.log-20170729.gz:45.79.85.54 - - [28/Jul/2017:18:57:24 -0700] "GET /faqs?active=true&limit=250 HTTP/1.0" 200 9561 "https://www.azurestandard.com/my-account/orders" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36 Edge/14.14393" 0.076 0.076 .

If we're no longer using the API or Beehive models, I suggest we drop them.

Landed in the API via https://github.com/azurestandard/beehive/pull/4995.

The property actualDeliveryBackdated is a boolean on the stop endpoints.

Spec out an endpoint to verify uniqueness of an email address. This is to be used for website issue #115 to verify the email address being used is unique.

The website has a “My Filters” section for product characteristics since azurestandard/website@98edbf187 (Settings & preferences "finished", 2014-10-16). This is similar UI to categories, brands, and tags (on sale, bargain bin, …). Are we sure we don't want to roll them into a single filter API / UI? I feel like separate package-search filters and UIs for each of these slightly-different relationships is just adding more maintainence work for a less usable API / UI. Having separate CRUD APIs for each model can make sense (e.g. brands can be managed by vendors, but we may want more control over piece categories and characteristics). So I'm fine making distinctions in the UI for managing brands/categories/tags/characteristics. I just think we'd be better off if we could collapse the product-filtering API/UI into a single field.

How do we feel about using tag and ancestor-tag for all of the filtering? Then we'd want a new endpoint to list possible tags (which would let us show different tag lists depending on authorization, e.g. new-no-on-sale only to folks with the products.change_product permission), and endpoints to set a customer's default tags. The search backend would have to collapse data from the related models into product and/or packaged-product tag fields, but we're already doing that (from ProductStatus to tag).

As I understand it, pasting the spec's JSON url into the URL input here should work. When attempting, I get this:

Filing this issue so we can discuss the requirements (particularly permissions) for updating payment methods through the API. With CustomerPaymentMethod.active planning to land in https://github.com/azurestandard/beehive/issues/1918, we'll want to add a way for customers to activate/deactivate payment methods. It looks like currently the only payment methods handled through the API are credit card based methods but I'm assuming we'll be rolling out support for others in the near future as well.

The idea for CustomerPaymentMethod.active is to replace to SavedCreditCard.visible_to_customer, but for beehive legacy implications, we'll need to keep it reverse compatible for the time being. With that said, this is probably a good a place as any to further the discussion around what effect SavedCreditCard.visible_to_customer has on CustomerPaymentMethod.active, and vice versa.

Update the /drops endpoint to accept geo coordinates as a parameter. If they are provided, sort the results by proximity to the given coordinates.

We need to update the API so customer service entering Amazon orders can skip the new 30-minute delay for parcel-carrier auto-verification (azurestandard/beehive#2547). That assumes Amazon orders are added using the API, which I'm not sure is the case. @tompetersjr is trying to pin this down.

@wking

Related to multiple email support (website issue 624):

Resending the confirmation email:

With the current api spec, there seem to be two ways to achieve this:

1. POST to /emails/resend - which requires a token that is only returned after initially creating the email (and is thus not possible to get again after page refresh, unless we stored it in localstorage or something, which at that point seems to overly complicate the task).
2. PUT to /email/{id} - which requires the user's password (arguably bad UX for such a simple task as having a confirmation email resent).

Since a POST request to /emails/resend seems specifically intended for this task it appears the recommended approach. However, a PUT request to /email/{id} is much easier since it does not require a token. Perhaps there may be a way to drop the token requirement for /emails/resend or otherwise PUT to ``/email/{id}` without a password? Anything I'm missing here?

Also, I don't see why a PUT to /email/{id}/resend with the email's ID wouldn't work (since the ID is returned on POST (creation) of the email via /emails/create and on the loading of emails (via GET to /emails), so it's accessible in all cases the front-end would need it for making a PUT to /emails/{id}/resend). Reading over the initial implementation of the API it seems this was the approach... I've read the PR notes here but since there's access to the ID I'm not sure on why this approach wouldn't work.

The API for Total Cases needs to be broken down by Frozen, Chill and Greenhouse.

So maybe something along...

"cases-shipped-frozen": {
    "description": "frozen quantity of shipped boxes and bulk stock",
    "type": "integer",
    "format": "int32"
}
"cases-shipped-chill": {
    "description": "chill quantity of shipped boxes and bulk stock",
    "type": "integer",
    "format": "int32"
}
"cases-shipped-greenhouse": {
    "description": "greenhouse quantity of shipped boxes and bulk stock",
    "type": "integer",
    "format": "int32"
}

See PDF Template: https://github.com/azurestandard/beehive/blob/226ec6956970fa83c220c4ee4b05d6e35cf27294/apps/shipping/templates/shipping/pdfs/cover_sheets.html#L83-L103

Product Data Check Types

Plural

GET Request

Get a list of all the product data check types.

Example:

https://api.azurestandard.com/product-data-check-type

Response:

[
  {
    "id": 1,
    "active": true,
    "name": "Incorrect Image"
  }
  {
    "id": 2,
    "active": true,
    "name": "Incorrect ingredients"
  }
  {
    "id": 3,
    "active": true,
    "name": "Incorrect physical characteristics (size, weight)"
  }
]

Product Data Checks

Paging would be handled like all our other endpoints.

Plural

GET Request

Get a list of all the product data checks.

Example:

https://api.azurestandard.com/product-data-check

Response:

[
  {
    "id": 1,
    "createdAt": "2018-10-16T08:53:47.213810",
    "createdBy": {
      "name": "John Doe"
    },
    "dataCheckTypeId": 1,
    "productId": 1234,
    "completedAt": "2018-10-16T08:53:47.213810",
    "completedBy": {
      "name": "Greg Smith"
    },
    "note": "My note here"
  },
  {
    "id": 2,
    "createdAt": "2018-10-16T08:53:47.213810",
    "createdBy": {
      "name": "John Doe"
    },
    "dataCheckTypeId": 2,
    "productId": 1234,
    "completedAt": null,
    "completedBy": null,
    "note": "My note here"
  },
  {
    "id": 3,
    "createdAt": "2018-10-16T08:53:47.213810",
    "createdBy": {
      "name": "John Doe"
    },
    "dataCheckTypeId": 2,
    "productId": 4321,
    "completedAt": "2018-10-16T08:53:47.213810",
    "completedBy": {
      "name": "Greg Smith"
    },
    "note": "My note here"
  }
]

Singular

GET Request

Get a list of all the product data checks.

Example:

https://api.azurestandard.com/product-data-check/3

Response:

[
  {
    "id": 3,
    "createdAt": "2018-10-16T08:53:47.213810",
    "createdBy": {
      "name": "John Doe"
    },
    "dataCheckTypeId": 2,
    "productId": 4321,
    "completedAt": "2018-10-16T08:53:47.213810",
    "completedBy": {
      "name": "Greg Smith"
    },
    "note": "My note here"
  }
]

POST Request (New Entry)

Create a new product data check entry.

Example:

https://api.azurestandard.com/product-data-check

[
  {
    "dataCheckTypeId": 2,
    "productId": 4321,
  }
]

Response:

[
  {
    "id": 2,
    "createdAt": "2018-10-16T08:53:47.213810",
    "createdBy": {
      "name": "John Doe"
    },
    "dataCheckTypeId": 2,
    "productId": 4321,
    "completedAt": null,
    "completedBy": null,
    "note": ""
  }
]

POST Request (Mark Completed)

Mark a data check as completed.

Example:

https://api.azurestandard.com/product-data-check/2/actions/mark-completed

Response:

[
  {
    "id": 2,
    "createdAt": "2018-10-16T08:53:47.213810",
    "createdBy": {
      "name": "John Doe"
    },
    "dataCheckTypeId": 2,
    "productId": 4321,
    "completedAt": "2018-10-16T08:53:47.213810",
    "completedBy": {
      "name": "Greg Smith"
    },
    "note": "My note here"
  }
]

A trip can be delivered by multiple trucks. For example: The first half of trip 1234 is delivered by truck 1 and the second half is delivered by truck 2.

We've discussed adding visual grouping/indication of this in multiple frontend (the Logistics App and the Driver App). In order to do support this, we need to know:

• [stop level]
  • Which truck a stop is delivered by
  • The order of the truck (in the route) the stop is delivered by
• [trip level]
  • Total truck count (this may not be necessary in all use cases, as it could be calculated from the trips)

Proposed property additions to achieve the above:

/stop

truckId : Int (sequential, e.g. truck id 1, truck id 2, where truck 1 handles the first part of the trip and truck 2 handles the second)

/trip

truckIds : Array (of stop-level truckIds for the trip's stops)

This endpoint is not currently in the spec and, as far as I know, never was.

It's being used here and here in the Logistics app.

Allow customers with Net Terms to Checkout. This may already be in the API-SPEC so please close if it is.

The response object for the product endpoint (https://azure-api-docs.netlify.app/#operation/findProductById) is not accurate. We should update it to what the API actually returns.

Documentation in azurestandard/beehive#2373.

Our current logic for them incorrectly assumes the payment is order-lines + shipping, but that's not going to be true if the customer had an outstanding credit/balance that got rolled into that payment. And checkout-payment seems to have not made it into the API spec anyway (see azurestandard/beehive@34e7a19cb for how we're setting it). Factors to consider:

• We break shipping out on invoices, so it makes sense to have a separate order.shipping. The total for an order is then (with #36) sum(orderLines.price) + order.shipping.
• With order.shipping, we have a hard time expanding to other auxiliary costs. For example, if we charge a small-order fee, we'd need a separate field order.small-order-fee. Maybe it's better to have order.fees, which would be an object like {'shipping': 1.23, 'small-order': 50.0}. That could give UIs some forward compatibility if we add additional fee-types later (they'll probably want to map the slugs to human-readable names, but if you see a slug you haven't mapped, and you don't want to automatically map, you can always just print the slug).
• With any sort of shipping-via-an-order-property approach, it's going to be hard to update shipping after adjusting an order line. For example, if you add a heavy order line, would you POST the line, wait for a response, and then re-GET the order just to update your shipping estimate? We don't do shipping estimates now, but we've talked about them a lot (especially for UPS orders), so I don't want to paint ourselves into a corner here. On the other hand, GET /order/{id} is pretty cheap at around 300ms (from BH-PW, but see also these notes on Slack), so maybe we don't need to embed the (expensive to generate) product at all.

Documentation:
https://docs.google.com/document/d/1XvoAyiSBuBviqL4lcjYMH7GXJu44b3JWb6BeNNvXwHI/edit?skip_itp2_check=true#heading=h.jdgkxrw0lvwv

Add geo coordinates to addresses, and geocode whenever an address is created or updated.

Whether or not we are going to need this is still up for discussion.

In discussions with @davidcross and @davidmcatee-azure about improving our SEO standings we would like the ability to store an SEO Title and Description for a category. This new fields would then be used by the website for our HTML Title and Meta Description tags.

These fields should be added to the /categories table as:

1. seo-name
2. seo-description

The following tasks will need to be completed in the following order:

1. API Spec needs to be updated - This Issue
2. Backend work - Beehive #3030
3. Internal Website for Data Entry - Internal-Website #190
4. Website will need to consume the data - Website #1736

Broken out of an issue from @davidcross https://github.com/azurestandard/beehive/issues/3965.

Update the customer endpoint to include the marketing slug.

For https://github.com/azurestandard/website/issues/759

See section 8.3.2 Address Book, in the website spec doc.

Customers need the ability to change their primary address in the Address Book of the new website.