[Feature] Improve New Business Registration Form to Leverage API & Editorial Pipeline

[elchris]

User Story

As someone who knows of a Black-Owned Business, or the owner of a Black-Owned Business
I want to Register a New Business but to also be guided as to whether the Business already exists, and be offered the ability to submit updates to the Business.
So I can avoid duplicating work or submitting multiple entries for the same Business.

Background

At React Rally we announced the newest version of our API, which is now public-facing:

https://api.rebuildblackbusiness.com/

It introduced two new endpoints:

• POST /api/v1/businesses to create a new Business Listing
• PATCH /api/v1/businesses/ID to update specific properties of an existing Business

Current Situation

We recently greatly improved our "New Business" "Registration" form which can be found off of the Listings Page: https://www.rebuildblackbusiness.com/businesses/

All submissions are funneled into a new entry into the production AirTable with the field "Approved" set to false, such that someone on our staff might review the submission, make any necessary changes and Approve it. Once that's done, the API application automatically synchronizes all of the AirTable data into its database.

This is our current Prod AirTable:
https://airtable.com/tblz9khS4nskrHYMF/viwYkK4LF8DPuUaYO?blocks=hide

Current Situation: Some Drawbacks

There currently is no easy way to signal to the user that a business's name may already exist in our database, and in some instances, a user may want to send-in multiple revisions. While the API does support the ability to search a business by name via the "search" parameter on /api/v1/businesses, it's also not being surfaced to end-users on the web site, so it's very difficult for them to tell whether a business already exists in our system.

New Possibilities

As part of the latest API release, we now have a dedicated AirTable base designed to ingest new listings or desired updates to existing listings. The system knows to make the appropriate correlations on "updates".

Here is our Editorial Pipeline Base:
https://airtable.com/tblXIjeThMr3lvs45/viwmTJ1MSxCyoIEge?blocks=hide

It is essentially a clone of the main AirTable Base, with a number of extra fields dedicated to the Editorial Lifecycle Process, including:

• Editorial Status:
  • Received
  • Under Review
  • Approved
  • Rejected
  • Processed
• Editorial Feedback
• Operation:
  • INSERT
  • UPDATE
• Request ID
  • tracks identifier of the request in the Developer Portal's "My Editorial Queue"
• Business AirTable ID
  • For UPDATE operations only, the identifier of the record in the Main AirTable Base
• Developer ID
  • The ID of the Developer Portal account which initiated the request
• Business ID
  • For UPDATE operations only, the identifier for the Business on the API Application

When a Developer initiates a POST or a PATCH operation as specified in the API Doc, a new entry will be automatically added into this AirTable base, and the developer will be able to track the progress of their submission in their "My Editorial Queue" in the Portal.

Desired Solutions

With these new capabilities, we should be able to offer to the end-user a "guided experience" to their submission. There could be any number of ways to execute it from a UI standpoint but at its core we should consider:

Acceptance Criteria

• Offering the ability to search for a business by name to see whether it exists.
• If one or more businesses are found, show them to the user, and make them confirm that they indeed still want to add this new listing, or just stop there
• Create a new business
• Look for helpful Error Messages and Suggestions coming in the API responses when creating a new business

Possible API Error Messages coming-back from the API when Submitting a New Business

• Exception: if there already is an editorial operation under review for a given business name
• Exception: if one or more businesses exist with the same name, and the matching businesses are shown in HATEOAS style in a "links" property
• Exception: on missing required minimal fields:
  • businessName
  • description
• Exception on either isPhysicalLocation or isOnlineOnly not having been set
• if isPhysicalLocation, Exception if missing any of these fields:
  • streetAddress, city, state, zip, latitude, longitude
• if isOnlineOnly, Exception on missing site

Enhancing the Existing New Business Submission Form

Within the scope of this experience, we're not yet concerning ourselves with updating an existing business.

• Create a new .env variable called EDITORIAL_API_KEY
• Obtain an API Key from the Developer Portal
  • assign the key to EDITORIAL_API_KEY
  • for production deployment, we will create a separate account with its own key
• This key can be sent as an x-api-key header in all the following API calls
• Enhance the existing Registration Form as follows:
  • Keep all the fields as-is
  • Hide everything below Business Name
    • Once the user enters a Business Name, issue a call to:
      • GET https://api.rbb-api.com/api/v1/businesses?search=business+name
      • if results do come-back, present the user with a list of results and try to link each business to their individual profile, by leveraging what @mbifulco is working on here
        • offer a [x] checkbox indicating "The business I'm entering is not among the above list"
      • if no results were found, of they clicked the above checkbox, then un-hide the rest of the existing form and let the user fill out the form as it current exists
      • To reduce our dependency on AirTable you might pull the list of categories from:
        • GET /api/v1/categories
  • When ready to submit the information:
    • Issue a POST https://api.rbb-api.com/api/v1/businesses with a JSON object in the body with the following properties
      • ownerEmail: if "I am the owner" was checked in the form
      • businessName
      • category
      • description
      • phone
      • either one of these fields set to true: isPhysicalLocation or isOnlineOnly , the other one set to false
        • isPhysicalLocation: true | false
        • isOnlineOnly: true | false
      • streetAddress
      • city
      • state
      • zip
      • serviceArea
      • site
        • the API will throw a descriptive error if the URL does not start with either https:// or http://
      • isAdult : true | false
      • inNeed: true | false
      • donationLink
        • the API will throw a descriptive error if the URL does not start with either https:// or http://
      • story
  • if a 409 response is returned, meaning "conflict", a JSON object will be returned with an Exception property whose value is a message friendly for the end-user. Consider rendering this message.
  • if successful response, then you can:
    • See the submission in your Editorial Queue
    • A few minutes later the submission should show-up in our Editorial AirTable Base