add subscription url to mailing list (ml) entry in contacts list

[haxwithaxe]

it would be nice to have a subscription link tied to the "ml" entry in the contacts. the HacDC public list moderates messages from nonsubscribers.

[slopjong]

Just for cross-referencing: https://github.com/SpaceApi/SpaceApi/issues/19#issuecomment-6465911

[rohieb]

I was also thinking about this. As an alternative, one can put the direct subscribe address in the same field, using mailto: schema syntax.

[slopjong]

What about this structure:

"ml": [
  {
    "subscribe": "http://.../list1",
    "email": "list1@example.com" 
  },
  {
    "subscribe": "http://.../list2",
    "email": "list2@example.com" 
  },
]

Since ml is changing the format what name do you propose as an alternative to ml? For me 'ml' is fine but rohieb already made a name change requested (status -> state) some time ago for compatibility purposes.

I think all the spaces will update to v13 anyway sooner than later so in fact compatibility arguments are not really valid ;-)

[rohieb]

What about mailing-list? ;-) Additionally to your example, I also thought of something like

"mailing-list": [
    {
        "subscribe": "mailto:list1-subscribe@example.org",
        "email": "list1@example.org" 
    }
]

(What follows here are a few thoughts about compatibility.)

There are always two sides for compatibility, the endpoints and the apps. Maybe the endpoints update quickly, maybe not, and maybe the apps update quickly or not. In any case, there will be a time where some spaces serve 0.12 and some serve 0.13 (and some still serve older versions), and a point where some apps expect 0.13 (this is fine as long as they additionally know 0.12) and some apps only expect 0.12 (because they don't know about 0.13 yet). So if I update my endpoint too quickly, there is the risk that I break some apps, which is bad.

Since I don't have the possibility to serve more than one version for my endpoint, I "officially" serve 0.13 and add the fields that were different in 0.12, which is possible because they have different names. I admit that this is a rather bad workaround (I still cannot set 'api'='0.12' and 'api'='0.13' at the same time), but I didn't think of a better solution for my endpoint. I also admit that we have to be creative for every new field name once we change it.

I could serve more than one version through different URLs though, but this is not much use if I can only enter one version into the directory. So in an ideal world™ there should be the possibility to enter the API version for each endpoint in the directory, and multiple URLs for multiple versions of an endpoint. And for that, we would have to update the syntax of the direcetory. And since we would change the syntax, we would also need a version number for the directory, and a clean (but minimal) spec (because, who knows, we might need to change the syntax again somewhere in the future). We could still serve the old syntax of the directory through the current URL, and specify a new URL which includes the new version number.

tl;dr:

• We are in Version Hell.
• We can exit the Hell by serving the endpoints with (multiple) version numbers in the directory
• To do this, we need to version the directory and a minimal spec for the directory.

[slopjong]

If I'm not wrong the api exists since the validator has been developed (the <, > and ! operators came later), I assume that app developers use it. If they don't they were not able to read the documentation or were just ignoring it.

In the case where an app breaks, (almost) all the apps are listed on the website so everybody knows where to get the source and many should be able to add the api support. If an app is yet missing, the spaceapiapp_app repository is where it should be added.

I don't really see a version hell, not with only 4 apps consuming the endpoints. Unknown apps with 2 users are not relevant. We don't provide something like AWS with hundreds/thousands of clients and millions/billions of users.

Maybe I should just make the api mandatory.

[slopjong]

The directory could look once a day if a new version was implemented by the endpoint and then keep track of it.