adds current directory schema and draft

[gidsi]

Starting to versioning the directory schema. Decided against versioning for this draft to make the switch easier (i also think the directory should always provide all versions until no one is using a specific one anymore)

New version would look like this: { "items": [ { "space": "your space name", "url": "https://example.com/spaceapi.json", "lastSeen": 12345678, "valid": true } ] }

[dbrgn]

Hm, so you propose adding a new format (in parallel to the existing format) which would require everyone to update code to use, but you suggest not adding versioning to the new version to make the transition easier? :)

[gidsi]

Ah, shoot. You are right, was a bit missleading, was kinda late :smile:

I decided against adding multi endpoint versions at this point to make it easier for now (like: "here is my v13, here is my v14" etc). But i want to keep all directory format versions in the directory that we're going to provide as long as someone is using it so you don't have to rewrite software which is using the old format (old format: { "spacename": "url", "spacename2": "url"})

In the end i would like to have something like this:

---

to get the old format

curl directory.spaceapi.net/v1

Output:

{
  "MyCoolSpace": "https://example.com/spaceapi.json"
}

---

new format

curl directory.spaceapi.net/v2

Output:

{
  "items": [
    {
      "space": "MyCoolSpace",
      "url": "https://example.com/spaceapi.json",
      "lastSeen": 12345678,
      "valid": true
    }
  ]
}

---

future format (just as an example)

curl directory.spaceapi.net/v3

Output:

[
  {
    "space": "MyCoolSpace",
    "url": {
      "v13": "https://example.com/spaceapi.json",
      "v14": "https://example.com/spaceapi.json?v=14"
    },
    "lastSeen": 12345678,
    "valid": true
  }
]

Hope its more understandable now :grin:

[dbrgn]

I agree about keeping the old format indefinitely, but why not go straight to a "future format" instead of this intermediate v2 format that's breaking but still doesn't contain version information?

[the-metalgamer]

I would directly go with the "v3" format. I would also suggest, that we don't support all versions. I would support the last, the current and the next version (i.e atm 0.12, 0.13 an 0.14)

[gidsi]

I consider these output formats, i wouldn't change the static file so far.

For "v3" we have a lot of open questions (e.g. would we have to change the input format for this to be able to provide multiple input formats? what will we delivere when someone wants to have v1 format but we have spaces with different versions? how can you identify the space if it has multiple endpoints? Would be a filter enough? Are we going to support just specific versions or all of them? etc. etc.) and i didn't want to wait for them to be answered. I would say that v2 is quite a simple format with a huge advantage over the old format and i would let it implement even beside a v3 as a different flavour.

[gidsi]

@dbrgn since the branch isn't mergable i would delete the branch and the PR and create a new one, would that be okay with you?

[rnestler]

@dbrgn since the branch isn't mergable i would delete the branch and the PR and create a new one, would that be okay with you?

Rebasing is not possible?

[dbrgn]

@gidsi also, would you mind sticking to the git commit message conventions regarding capitalization and imperative mood? :slightly_smiling_face: Chris Beams gives some very good rationale for that convention.

[gidsi]

Since we're sticking to the static json file as the directory and putting everything dynamic into the api service we can close this.