KenEucker/biketag-api

Consider renaming api interfaces to be as succinct as possible

Closed this issue · 2 comments

As we approach the alpha version of this API I think it would be good to revisit the contract we are making with developers. If we remove the verb get from methods like getTag and combine the getTag and getTags functionality based on the payload passed in, we can end up with a very easy to understand set of methods that simply pertain to working with BikeTag data:

With this, we would end up with an API contract that looks like this:

const tag1 = biketag.tags(1)
const allTags = biketag.tags()
const deletedTag = biketag.delete(1)
const updatedTag = buiketag.update({ tagnumber: 1, foundImageUrl: null }) 

Which, I think, would feed into the exposed gunjs data method of the API:

const tag1 = biketag.data().get('tags').get('portland-tag-1').once()

Since the most available API will always be powered by GunDB, I think it makes sense to have the interface for the BikeTag API be as similar as it can be.

Additionally, it is unclear yet if we are going to offer the ability to create Players or Ambassadors or even Games with the API. I think that v2.0 definitely will not from the start but maybe with v2.5 that could be a goal (depending on adoption). Because of this, methods like biketag.delete can always be in the context of a Tag for a preset game.

biketag@1.10.3 introduces these interfaces and takes advantage of the existing singular and multiple queries, where applicable. For getTag, I've removed the Imgur adapter implementation as it was doing the same thing as the getTags implementation was. For the Sanity adapter, direct querying for a single tag is possible so that getTag implementation remains, and getTag on the BikeTagClient will choose a client implementation if it exists.

this interface has been added for all data types:
game (singular by design, as it sets the context for the remaining interfaces)
tags
players
ambassadors
settings

The players interface has been implemented as well, and can be used as follows:

biketag.players() // all players for the game
biketag.players('Ken') // an array with the Ken player if it exists
biketag.players(['Ken']) // an array with the Ken player if it exists
biketag.players(['Ken', 'Evan']) // an array with the Ken and Evan players for those that exist

This interface (biketag.players) is synonymous with using the existing methods:

biketag.getPlayers() // all players for the game
biketag.getPlayer('Ken') // an array with the Ken player if it exists
biketag.getPlayers(['Ken']) // an array with the Ken player if it exists
biketag.getPlayers(['Ken', 'Evan']) // an array with the Ken and Evan players for those that exist

These interfaces all work and will only be tested for accuracy of routing to the correct get method, beyond that the only thing needed to test are the units themselves (the client adapter methods).