Make SpaceAPI REST again

[miko007]

In my opinion, the API should be defined not only as a schema, but also as a RESTful service. I understand, that this would basically break the "single json file hosting" approach some spaces take, but maybe a flag could be introduced, if REST functionality is available or not.

If an application only cares about the state::open value, it is utter nonsense to poll the whole schema. My proposal is, that each root key should also be a GET endpoint that can be queried separately. So if you call https://space.tld/api/state, you should only get the state object, if that makes sense.

I am looking forward to hear the opinion of all of you on that matter.

[dbrgn]

If an application only cares about the state::open value, it is utter nonsense to poll the whole schema.

Do you think the few bytes saved are worth the tradeoff that every space now needs to set up and maintain a full HTTP API server?

Right now a lot of spaces just put a static JSON file on their webserver. In my opinion it's important that this approach is retained, because it significantly lowers the entry hurdle.

However, a community project could provide a caching server that regularly fetches the data from all endpoints and provides those through a RESTful API. IIRC @gidsi started something like that in the past, but I don't know about the state.

[gidsi]

In my opinion, the API should be defined not only as a schema, but also as a RESTful service. I understand, that this would basically break the "single json file hosting" approach some spaces take, but maybe a flag could be introduced, if REST functionality is available or not.

If an application only cares about the state::open value, it is utter nonsense to poll the whole schema. My proposal is, that each root key should also be a GET endpoint that can be queried separately. So if you call https://space.tld/api/state, you should only get the state object, if that makes sense.

I am looking forward to hear the opinion of all of you on that matter.

Hey, thanks for reaching out.

Sounds interesting, what do you want to achieve with that solution? I've been working on something like that for a fact, but didn't put to much work into it lately (and also it goes the different approach, edit single fields, get is only available for the whole file so far).

You can find the project here (since i didn't put to much work into it its not on the website nor really public)

Here you can see an interface for the api.

But that's for the approach that the space itself provides an API to the file (which i wouldn't recommend nor think is realistic that a lot of spaces would do that without showing significant benefit for it).

Another approach is what @dbrgn mentioned, a caching service. Right now we use one internally (internally as in we will change it at any time without giving notice, not internally as in not reachable from the outside), reachable at api.spaceapi.io/collector, which is the system providing us with metrics and holding the state for the SpaceAPI API (openapi file) itself. We talked about making the data available through the API too, but so far it's more something i need while developing apps, nothing with a huge pull (right now you can just filter on validity, but that's more like a start and a more to come).

So, if you tell us more what you want to do and what you need it for we might be able to help :)

[jabelone]

If an application only cares about the state::open value, it is utter nonsense to poll the whole schema.

There is absolutely no benefit to this other than saving a few bytes of data. A lot of client implementations would become vastly more complex and would introduce a lot more overhead if they had to poll dozens of endpoints to get all the info they need.

My 2c, is this would be a silly over complication. We dynamically generate a JSON endpoint as part of our membership portal and it would be a lot of extra work to implement a full REST API when there is absolutely no need. This is something we would not waste time doing and would likely drop support for the space API if introduced as a requirement.

[miko007]

This is something we would not waste time doing and would likely drop support for the space API if introduced as a requirement.

I maybe have not been clear enough on this point, but i proposed this to be an optional thing. The whole purpose on opening this issue has been, that we are currently implementing exactly this (which is effectively 10 loc in an nodejs/express app), but i would like to have it optional but standardized.

it is as simple as introducing a bool attribute in the root tree like "rest" : true, so the client knows, it can use the endpoints if necessary.

I think about things like the esp8266 with limited processing power. if we have like 500 events and 1000 projects in our full api dump, it will be noticeably slower on an embedded device to parse the whole tree instead of i.e. just the state subtree, if that makes any sense.

[gidsi]

I maybe have not been clear enough on this point, but i proposed this to be an optional thing. The whole purpose on opening this issue has been, that we are currently implementing exactly this (which is effectively 10 loc in an nodejs/express app), but i would like to have it optional but standardized.

Sounds great, will it be available somewhere? Maybe you want to add it to the website :)

it is as simple as introducing a bool attribute in the root tree like "rest" : true, so the client knows, it can use the endpoints if necessary.

I think about things like the esp8266 with limited processing power. if we have like 500 events and 1000 projects in our full api dump, it will be noticeably slower on an embedded device to parse the whole tree instead of i.e. just the state subtree, if that makes any sense.

That's something i don't fully understand, if you add it to the schema don't you have to pull the whole json before you would find out that you didn't have to do it? Or you would have to save the information that the single attributes are available as a REST resource somewhere. I think it's a nice idea to just pull the data that you want but i can't think of a scenario that you would need the information dynamically (esp8266 sounds a lot like it will be just looking at your own endpoint and for that you already have the information that you just have to call a specific route for the information that you need).

[rnestler]

This is something we would not waste time doing and would likely drop support for the space API if introduced as a requirement.

I think we all agree here that it should be an optional part :slightly_smiling_face:

[gidsi]

If an application only cares about the state::open value, it is utter nonsense to poll the whole schema.

There is absolutely no benefit to this other than saving a few bytes of data. A lot of client implementations would become vastly more complex and would introduce a lot more overhead if they had to poll dozens of endpoints to get all the info they need.

My 2c, is this would be a silly over complication. We dynamically generate a JSON endpoint as part of our membership portal and it would be a lot of extra work to implement a full REST API when there is absolutely no need. This is something we would not waste time doing and would likely drop support for the space API if introduced as a requirement.

Hey, thanks for your comment :) Nobody said that we should make it mandatory, in fact he said himself that he doesn't want to break the single file approach in his initial post. And from my point of view we will never drop the single file approach ever. Apparently there is somebody who has the need to save the few bytes and where it's not a silly over complication, it would be nice if you could be a bit more polite.

[dbrgn]

@miko007 maybe you could set up a repository with a specification RFC at https://github.com/spaceapi-community/? If the community thinks this is a good idea, then more spaces will start to implement it. To signal support for the REST extension, you could add an "ext_rest": "v1" field to your plaintext SpaceAPI endpoint. (The ext_ prefix will ensure that it will never collide with a standardized field.)

We generally try to keep the "core SpaceAPI" quite small, with a lot of community extensions developing. If one of those extensions takes off and is implemented by many spaces, it could always be standardized. (A good example for a successful extension spec is https://spaceapi.ccc.de/, see spec.)

@gidsi @rnestler if you agree, then we can close this issue. @miko007 let me know if you want a repo and membership in the spaceapi-community organization :slightly_smiling_face:

[miko007]

@dbrgn as you mentioned a caching service, i quickly implemented a proof of concept of one. There i also implemented the REST-ish part, so people can explore, how something like this would behave in my imagination.

A currently live version can be explored here. One can obtain information about a specific space by appending the path from the assignment found under / and get more specific information by appending the attribute, like /devtal/status.

The assignment is necessary, because i had to elminate not URL safe chars and slashes for the routing to work. Sorry about that. Source is https://directory.spaceapi.io.

It also filters spaces, that do send HTTP 200 but no valid JSON(which are a LOT).

[gidsi]

The assignment is necessary, because i had to elminate not URL safe chars and slashes for the routing to work. Sorry about that. Source is https://directory.spaceapi.io.

It also filters spaces, that do send HTTP 200 but no valid JSON(which are a LOT).

If you would switch to https://api.spaceapi.io instead you would just get valid endpoints :)

[miko007]

Thank you @gidsi, this is nice to know. I am not shure if i care atm, because the code validating the endpoints is already in place, so why shouldn't it do some work? :D

I probably change the url, though, so there is less to parse.