Express API Information

Introduction

This section of the documentation covers the API of the Wayfinder application as illustrated in Figure 1.

The Wayfinder application uses an Application Programming Interface (API) leveraging Express.js to serve its backend. For a more technical breakdown of the end points and methods, please refer to the Swagger documentation.

For info more specific to Express.js as a whole, view the Express.js documentation.

flowchart LR
    F(Frontend) -- User Request --> A(Express API)
    style A stroke:green,stroke-width:2px
    A -- MongoDB Query --> D(MongoDB Database)
    D -- Results --> A
    A -- Server Response --> F

Loading

[Figure 1. Wayfinder Architecture Data Flow Model]

Getting Data Into the Database

The Wayfinder API can populate and update your database. The API has a protected endpoint, allowing you to automate this process with scripts or web scrapers. Automating this process is beneficial as it reduces the time and effort required for updates. By defining your own Extract, Transform, and Load (ETL) scripts, you can always keep the database up-to-date as new information comes in.

The API is configured to use the website and locality values as a composite key to make updating and adding new data easy.

To push data to the API, follow these short steps:

1. Set your Bearer Authorization to the SCRAPER_KEY in your .env file.

2. Set your request target to the /api/locations endpoint.

3. Set the new location data as the request body using the location schema.

4. Send your request(s) to the target using the PATCH method.

If you receive a 403 status code, double-check that the location data you're sending is valid.

Congratulations! By following these steps, you've introduced new data to your database.

Seeding Data to the Application

Seeding is the process of populating a database (or application) with initial data to ensure the application will function properly.

Seeding is done using a GET request on the /locations endpoint. Targeting this end point will return all location data in the database, fully populating information for the Wayfinder application. This endpoint returns a larger amount of data and should be used sparingly to minimize mobile data consumption for end users.

Updating Data in the Wayfinder Application

To address the concern of repeatedly sending large data sets and optimizing the Wayfinder application, the API has implemented a POST method on the /api/locations endpoint. By using this endpoint in your develoipment, you can retrieve a smaller dataset from the API, focusing on data with recent updates and avoiding downloading unchanged data. Follow these steps to send a curated set of data to the application, reducing data consumption for the end user.

1. Set your request target to the /api/locations endpoint.

2. Set the requested dataset as the request body shown in Figure #.

3. Send your request(s) to the target using the POST method.

If you receive a 403 status code, double-check that the service type you are sending is valid.

{ serviceType: "ServiceBC" }

[Figure #. Example Request Body for locations POST method ]

Congratulations! By following these steps you've reduced data consumption by updating one set of data.

Getting Data From the User

To guide analytics and user-submitted reports, the Wayfinder application collects usage data. Both analytics and reports use database schemas for consistency.

The Wayfinder application is configured to take usage data for the purpose of analytics and user-submitted reports. Both analytic and report formats follow schemas for consistency. Using appropriate naming schemes, user-submitted reports are sent to the API's /api/report endpoint, and analytic data is sent to the /api/report endpoint.

Schemas

Using the defined schemas allows the Wayfinder application to gather and hold consistent data, making data management simple. Users are able to submit reports through the application, as well as opt-in or opt-out of sending anonymous usage reports. In this section of the manual, you will find the schemas being used.

Report Schema

The Report schema is designed to store and parse user-submitted reports. The model for this schema is illustrated in Figure 2.

• Latitude and Longitude: The geographic coordinates where a user report was submitted
• time: A Date object storing the submission time
• eventType: The type of event or activity the user is reporting on
• details: Additional information about the event
• phone: An optional value providing the user's phone number if they wish to be contacted
• ticketNum: A report reference number.

type Report = {
  latitude: number;
  longitude: number;
  time: Date;
  eventType: string;
  details: string;
  phone?: string;
  ticketNum?: string;
};

[Figure 2. Report Schema]

Analytic Schema

The analytic schema being used is as follows (Figure 3):

• latitude: Geographic latitude of the user at the time analytic was captured
• longitude: Geographic longitude of the user at the time analytic was captured
• usage
  • search: Item being searched for during the capture
  • function: The functionality of the application was being used
  • serviceType: The type of service was being searched for
  • setting:
    • value: The setting was changed to this value
    • type: What setting was changed
• date: Date the analytic was captured

type Analytic = {
  latitude: number;
  longitude: number;
  usage: {
    search?: string;
    function: 'find service' | 'find location' | 'report';
    serviceType?: string;
    setting? : {
        value: string | boolean
        type: string
    }
  };
  date: Date;
};

[Figure 3. Analytic Schema]

Location Schema

The database stores all location data using the SingleLocation blueprint seen in Figure 4, making it consistent and easy to use across the application.

• Contact
  • Fax: Fax number for the location
  • Phone: The main phone number for the location
• Services: A list of services offered by the location
• ServiceType: Classification of location, e.g., ServiceBC, BC Housing, ICBC, etc.
• Address
  • Province: Shorthand for province.
  • Street: Street Address
  • Postal Code: Postal Code of Location
  • Region: The area this location is in, e.g., Capital, Surrey, etc
  • County: The territorial division of location
  • Locality: The locality that the location resides in
  • Label: Full mailing address
• Locale: Location Title + Identifier
• Website: Official Website corresponding to the location
• Latitude: Latitude of Location
• Longitude: Longitude of Location

type SingleLocation = {
  contact?: {
    fax?: string;
    phone?: string;
  };
  services: [string];
  serviceType: string;
  address: {
    province: string;
    street?: string;
    postal_code?: string;
    region?: string;
    county?: string;
    locality?: string;
    label?: string;
  };
  locale: string;
  website: string;
  latitude: number;
  longitude: number;
};

[Figure 4. SingleLocation Blueprint]

Authentication and Authorization

Wayfinder uses Authentication and Authorization to protect the Analytical and Report data stored in MongoDB. To protect access to this valuable data, Wayfinder makes use of user accounts. To create user accounts, an administrator-level account must be used.

User Accounts

The Wayfinder application does not make use of user accounts for the end-user experience. However, accounts are created and managed for gathering and maintaining the analytical data stored within the database.

Creating an account

To create a user account in the current system, there is currently no frontend interface available. However, detailed instructions and information on creating and maintaining user accounts can be found in the API's Swagger documentation.

Gathering data for PowerBI Reports

Data can be collected using the Wayfinder API for analysis and event monitoring. The developers at Wayfinder make use of PowerBI for analyzing data, but any tool accepting JSON values and Basic Authorization will be compatible.

For a more specific guide on connecting PowerBI Desktop, visit this link.

The Wayfinder Application's user accounts are authorized using basic authentication due to its compatibility with Microsoft PowerBI.

Figure 5 below shows a visual representation of the user authentication and data retrieval used by the Wayfinder Backend. It illustrates the interactions between the User, API, and MongoDB Database. This process is critical for verifying user credentials and maintaining data confidentiality.

1. User Request: The user sends a request to the API with their authentication (username and password).

2. Verification: The API forwards the request to the database to verify the credentials.

3. Valid Credentials: If the provided credentials are valid and match an entry in the database, the database responds to the API Server, indicating the validity of the request.

4. Data Processing: The API continues to process the user's request.

5. Data Retrieval: The API Server sends a request to MongoDB to retrieve the requested data.

6. Results Returned: The Database responds to the API Server by sending the requested results.

7. Results Returned to the User: The API Server then sends the results of the query back to the user.

8. Invalid Credentials: If the provided username and password are invalid, the database responds to the API server and indicates the user was not found.

9. Authentication Failure: Upon receiving an invalid response, the API Server informs the user that the authentication process has failed.

sequenceDiagram
    participant User
    participant API
    participant MongoDB

    User->>+API: Send request with Basic Auth credentials
    API->>MongoDB: Verify user credentials
    alt Valid credentials
        MongoDB-->>API: User verified
        API->>MongoDB: Process query
        MongoDB-->>API: Return results
        API-->>User: Return results
    else Invalid credentials
        MongoDB-->>API: User not found
        API-->>User: Authentication failed
    end

Loading

[Figure 5. Sequence Diagram of User Authentication and Authorization for a Request]