API Changes

[joshcampbell191]

@mattpannella @neil-morrison44

I've been making some progress on refactoring the updater codebase to introduce some new features (APIs, category landing pages, author landing pages, etc.).

While looking into the cores.yml, I noticed that we're still tracking the prerelease and tag_name for repositories that are using releases as a deployment strategy. Are either of you using these? I'm pretty sure these were created prior to the download_url so I doubt they have much use (other than additional metadata).

Are you guys okay if we axe them?

- username: agg23
  cores:
  - id: agg23.Arduboy
    display_name: Arduboy for Analogue Pocket
    repository:
      platform: github
      name: openfpga-arduboy
      prerelease: false
      tag_name: 0.9.0
    requires_license: false
    download_url: https://github.com/agg23/openfpga-arduboy/releases/download/0.9.0/agg23.Arduboy.0.9.0.zip
    platform_id: arduboy
    description: A small, portable Arduino console.
    version: 0.9.0
    date_release: '2022-09-03'
    platform:
      category: Handheld
      name: Arduboy
      manufacturer: Arduboy
      year: 2016
    assets:
    - platform: arduboy
      extensions:
      - hex
    sponsor:
      github:
      - https://github.com/sponsors/agg23

[mattpannella]

all good to drop them on my end

[neil-morrison44]

Same here, Pocket Sync doesn’t use them anymore

[joshcampbell191]

@mattpannella @neil-morrison44

I'm looking into a few more changes to the API in order to have it be more focused around the metadata coming from the core definition files and was thinking of dropping display_name in favor of platform.name. This change would also better align the inventory to Analogue OS. I could simply map it for backwards compatibility on your end. This may lead to some confusion when multiple cores exist for the same platform (ie: Analogizer cores, bududes GB / GBC cores) but seems pretty clean otherwise. What are your thoughts?

[neil-morrison44]

@joshcampbell191 think that's fine with me, Pocket Sync doesn't use display_name just now

[mattpannella]

when I get home I'll have to double check but I'm fairly certain I'm not using it at all in pupdate. I think just the inventory is

[joshcampbell191]

After some more thinking, I was also looking at removing sponsor from the API. I know this is probably un unpopular opinion however the information is available in the source repositories. I was simply exposing them through the API by reading the contents of the .github/FUNDING.yml file in the repositories.

The same goes with the requires_license flag. These can be inferred by adding warning for missing required files that aren't present.

I think it would be best that the repository reflect the information in the core metadata files to avoid scope creeping.

[joshcampbell191]

I'm just about ready to release the changes for the refactor. I made another change to the assets by exposing all of the data_slots regardless of their status.

Here's an example: Before:

{
            "identifier": "AwesomeDolphin.SpaceInvaders",
            "repository": {
                "platform": "github",
                "owner": "AwesomeDolphin",
                "name": "openFPGA-SpaceInvaders"
            },
            "download_url": "https://github.com/AwesomeDolphin/openFPGA-SpaceInvaders/releases/download/1.0.0/AwesomeDolphin.SpaceInvaders_1.0.0_2024-01-02.zip",
            "platform_id": "spaceinvaders",
            "version": "1.0.0",
            "release_date": "2023-12-25",
            "platform": {
                "category": "Arcade",
                "name": "Space Invaders",
                "manufacturer": "Taito",
                "year": 1978
            },
            "assets": [
                {
                    "platform": "spaceinvaders",
                    "filename": "invaders.rom"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "0.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "1.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "2.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "3.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "4.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "5.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "6.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "7.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "8.raw"
                },
                {
                    "platform": "spaceinvaders",
                    "filename": "9.raw"
                }
            ],
            "replaces": null,
            "requires_license": false,
            "sponsor": null
        }

After:

{
            "identifier": "AwesomeDolphin.SpaceInvaders",
            "platform": "Space Invaders",
            "category": "Arcade",
            "manufacturer": "Taito",
            "year": 1978,
            "release_date": "2023-12-25",
            "version": "1.0.0",
            "repository": {
                "platform": "github",
                "owner": "AwesomeDolphin",
                "name": "openFPGA-SpaceInvaders"
            },
            "assets": [
                {
                    "name": "Rom",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "invaders.rom",
                    "extensions": null
                },
                {
                    "name": "SoundUFO",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "0.raw",
                    "extensions": null
                },
                {
                    "name": "PlayerShoot",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "1.raw",
                    "extensions": null
                },
                {
                    "name": "PlayerDie",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "2.raw",
                    "extensions": null
                },
                {
                    "name": "InvaderDie",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "3.raw",
                    "extensions": null
                },
                {
                    "name": "FleetMove1",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "4.raw",
                    "extensions": null
                },
                {
                    "name": "FleetMove2",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "5.raw",
                    "extensions": null
                },
                {
                    "name": "FleetMove3",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "6.raw",
                    "extensions": null
                },
                {
                    "name": "FleetMove4",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "7.raw",
                    "extensions": null
                },
                {
                    "name": "UFOHit",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "8.raw",
                    "extensions": null
                },
                {
                    "name": "ExtendedPlay",
                    "required": true,
                    "parameters": {
                        "core_specific_file": false,
                        "instance_json": false
                    },
                    "filename": "9.raw",
                    "extensions": null
                }
            ],
            "requires_license": false,
            "sponsor": null
        }

Note that I broke down the parameters into the individual flags so they don't have to be parsed. Also, this shouldn't impact v0, v1 or v2.

Let me know what you guys think.