shift-org / shift-org/shift-docs

Consider renaming database and/or API fields for clarity

Open
#555 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

API backend database enhancement question
Dominant language
JavaScript
Stars
30
Forks
25
Avg merge
9m
Merged PRs (30d)
1

Description

Some fields in the calevent and caldaily database tables can be a bit difficult to understand. Some examples:

  • calevent.name is the organizer name, calevent.title is the event title; "name" can be misconstrued as "event name"
  • calevent.locdetails instead of location_details
  • calevent.time is implicitly start time, but calevent.endtime is explicitly end time
  • caldaily.id is actually a foreign key pointing to calevent.id, and caldaily.pkid is the "true" id of the occurrence

MySQL allows columns to be up to 64 characters long, so we have some room if we want to make them longer for clarity.

Related, the events API output mainly mirrors the database column names, but doesn't strictly need to.

  • The caldaily_id field surfaces the internal db name which is irrelevant to API consumers. We could probably make it something more meaningful like occurrence_id.
  • Some fields aren't useful, e.g. hideemail. If hideemail = true then the backend ensures that email = null in the output; there shouldn't be anything for the API consumer to do. If hideemail = false then the email is provided and there's also nothing for the API consumer to do.
  • Boolean fields like featured could possibly be renamed to is_featured to better match boolean conventions.

This is also generally true for the manage_event and retrieve_event endpoints, though we don't currently (and haven't historically) had any external consumers for those APIs. We should keep consistency between the endpoints where possible and beneficial, though.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inventorying the calevent and caldaily database fields and the events, manage_event, and retrieve_event endpoint outputs described here. Before implementation, establish which names should change and how consistency will be maintained across database and API responses; done would require an agreed scope and coordinated updates.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, mysql
Domain
api, backend-api-design, databases
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.