search

AdmiralGT / botc-scripts

Blood on the Clocktower Script Database
https://botc-scripts.azurewebsites.net/
MIT License
20 stars 10 forks source link

Feature: Make script versions available through the API #372

Closed GarethOates closed 8 months ago

GarethOates commented 8 months ago

Description Currently it's possible to see all the scripts via the Django API at botcscripts.com/api/scripts, but I can't find any method to see which versions of a given script are available.

It would be nice with a /versions endpoint or similar so it's easy to programmatically determine which versions exist for a given script.

Additional context I'm trying to make a generic API for blood on the Clocktower data that is always up to date with the latest characters, announcements and custom scripts.

AdmiralGT commented 8 months ago

Thanks for the request, trying to understand the use case a bit more and propose some ideas. Firstly, some background:

The site splits scripts into 2 separate object types, one being the ScriptVersion objects, which is actually what you'd recognise as a script, a JSON file with a set of characters with some metadata attached (including the version of this script iteration). These are collected into Script objects, which is basically a ManyToMany field of ScriptVersions to collect the history of a script. The only identifying field of that is the script name and then the ScriptVersion keys for that script.

The /scripts endpoint is actually the set of ScriptVersion objects that exist in the database. ScriptVersions aren't themselves linked to other ScriptVersions, except through sharing a Script ForeignKey. I don't think it makes much sense to expose that ForeignKey over the API since it's not meaningful to the user and they can't use the key for anything else (since it is a separate key from the ScriptVersion primary key).

I don't however want to expose Script objects over the API for a couple of reasons

  1. It would be a naming nightmare. It would probably end with /script and /scripts which is just eww all over.
  2. They're not really useful from a user perspective.

I think this means a /versions endpoint is out since architecturally, it's only relevant to Script objects and they're not objects presented over the API.

At the moment, you can query the API with the search parameter which will find the closest named script. If you include the all_scripts=on parameter then you'll get all versions so the top results should be the closest match to the search result.

This could be a slightly nicer user experience in allowing you to filter by name (which would then return all the exact name matches).

Is the search function sufficient or is adding the name field for an exact match a requirement?

GarethOates commented 8 months ago

Thanks for the timely and considered response. 👍

I wasn't aware of the ability to search via the api directly and get a json response. I should have realised. I think I've figured out a way to search for what I need now. Thanks.