shift-org / shift-org/shift-docs
Consider renaming database and/or API fields for clarity
Nobody has claimed this yet.
- 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.nameis the organizer name,calevent.titleis the event title; "name" can be misconstrued as "event name"calevent.locdetailsinstead oflocation_detailscalevent.timeis implicitly start time, butcalevent.endtimeis explicitly end timecaldaily.idis actually a foreign key pointing tocalevent.id, andcaldaily.pkidis 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_idfield surfaces the internal db name which is irrelevant to API consumers. We could probably make it something more meaningful likeoccurrence_id. - Some fields aren't useful, e.g.
hideemail. Ifhideemail = truethen the backend ensures thatemail = nullin the output; there shouldn't be anything for the API consumer to do. Ifhideemail = falsethen the email is provided and there's also nothing for the API consumer to do. - Boolean fields like
featuredcould possibly be renamed tois_featuredto 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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