spaceapi.io

[niccokunzmann]

:clipboard: Description

:link: Data

This badge should show whether a hackerspace using the https://spaceapi.io is open or closed.

Data can be retrieved from two kinds of endpoints:

1. The spaceapi directory

   • JSON: https://directory.spaceapi.io/
   • documentation: https://github.com/SpaceApi/directory/issues/166

   This will be used to retrieve the url of the endpoint (2). /spaceapi/state/name/:hackerspaceid e.g. /spaceapi/state/AFRA

2. The endpoint
   e.g. https://spaceapi.afra-berlin.de/v1/status.json /spaceapi/state/url/:apiurl

:microphone: Motivation

I would like to be able to show a badge that displays whether my hackerspace is open.

[dbrgn]

Note: It's better to query the endpoint directly. The directory does have a caching function, but it's not guaranteed to remain that way forever and it's better to use the more decentralized approach 🙂

[niccokunzmann]

@dbrgn, so I would understand that the implementation (2) is most useful and (1) is of less importance..

[dbrgn]

@niccokunzmann I'm not sure how shields works in the background. I assume a service fetches the information server-side, right?

Every hackerspace/makerspace in the SpaceAPI directory has an endpoint (URL) that returns JSON conforming to the SpaceAPI schema. If you know that URL (you could let the user enter it to parametrize the shield), you can fetch the URL, and extract the desired information, all without querying the directory. (In the case of the opening status, you would extract the sensors.state.open JSON field.)

Some things to consider:

• URLs would need some kind of escaping obvously
• By supporting arbitrary URLs, that would leave open some room for reflected DoS (you could query endpoints indirectly through shields.io). However, there isn't really any significant amplification and I find the risk quite low. An alternative would be to just use the space name as a parameter, and look up the URL in the directory. In that case, it would only allow pre-validated URLs. On the other hand, then you'd need to do 2 queries for a single update, as opposed to just one.

[calebcartwright]

@dbrgn

I'm not sure how shields works in the background. I assume a service fetches the information server-side, right?

We're currently in the process of trying to add some documentation largely geared towards maintainers/vendors/etc. of upstream services, sharing the draft version in case it's helpful: https://github.com/badges/shields/blob/7da38f835411da4adc892ca7927f531481c56232/doc/service-integrations.md

However, the short version is yes. Shields returns svgs (or pngs) to our users that requested badges, and in order for us to created badges that have dynamic data points, the Shields badge server has to reach out to the corresponding system of record.

We integrate with nearly 1k services/platforms/etc. for data that goes into various dynamic badges, and as part of that we've got the standard concerns like uri encoding, parameterization, etc. well handled and in a pattern our users are quite familiar with, so we should be all set there.

The DoS question comes up from time to time, so it's something we intend to cover in the aforementioned docs but in general we don't view this as something that upstream providers should be concerned about in typical integration patterns.

For the Shields.io environment we have CloudFlare fronting all incoming traffic and utilize their dos protection services. That in turn transitively provides some protection to the data providers as well. Additionally, the nature of the Shields.io runtime environment results in the requests we make to those data providers seem like all incoming Shields traffic is coming from a very small number of clients. The combination of those two factors, along with the fact that many of the data providers we integrate with have their own protections in place, makes us think the attack vector through Shields would be poor and inefficient and is accordingly not typically a significant risk.

Sounds like you are generally of the same opinion for this particular case too :+1: However, there are mechanisms we can employ to reduce the traffic Shields would send your way if that is, or becomes, a concern and we're happy to chat if you have any additional questions.

[calebcartwright]

Additionally, a few questions for you @dbrgn and/or @niccokunzmann around some typical items we consider when evaluating adding badges that require integration with a new service/data provider:

• Is there any public documentation on the API? (I suppose the endpoint one given the discussion above)
• Are there currently any rate limits on the endpoint, or if not, any active discussions around adding any?
• I'm seeing between a 1-2.5 second response time using the example endpoint from the OP, is this fairly typical of what we could expect? (admittedly anecdotal, I'm in the US, and most of the responses were closer to the ~1.5 second mark)
• What channel would be best for us to utilize in the future should we need to report an outage/issue/etc. or just have a question? Would it be https://github.com/SpaceApi/directory?

[dbrgn]

Is there any public documentation on the API? (I suppose the endpoint one given the discussion above)

Yes, general information is at https://spaceapi.io/ and the schema for the endpoints is at https://spaceapi.io/docs/.

Are there currently any rate limits on the endpoint, or if not, any active discussions around adding any?

Since all endpoints are operated by different people/organizations there might be theoretially, but I don't think there are any limits in practice.

I'm seeing between a 1-2.5 second response time using the example endpoint from the OP, is this fairly typical of what we could expect? (admittedly anecdotal, I'm in the US, and most of the responses were closer to the ~1.5 second mark)

That will wildly vary. Some spaces might have quite fast response times, e.g. the space where I'm involved is reachable in <200ms from where I live: http://status.crdmp.ch/. Other endpoints might be dynamically generated backed by slow databases, or they might be operated from a Raspberry Pi. In the end, it's an unknown system serving JSON data, we can't really know more than that 🙂

What channel would be best for us to utilize in the future should we need to report an outage/issue/etc. or just have a question? Would it be https://github.com/SpaceApi/directory?

The endpoints themselves document the contacts for reporting issues/problems. For example here you see "issue_report_channels":["email","twitter"]. That means that issues can be reported via email or twitter, and those values are in the contact section.

Of course if the endpoint is down then you can't access this information. If you have any kind of question, then the best place would be the SpaceAPI project channel on Matrix or IRC:

IRC: #spaceapi on Libera.chat
Matrix: #spaceapi:matrix.coredump.ch

[chris48s]

I think if we implement this

1. We have the user specify the instance as part of the request rather than querying the directory so we make 1 api call, not 2.
2. It would make most sense to view each hackerspace as its own entity rather than 'spaceapi' as a centralised service. Each hackerspace API may have its own characteristics when it comes to performance, rate limiting, etc and they're going to vary - we can't really generalise. It is probably most analogous to something like self-hosted JIRA or SonarCloud where there are lots of instances out there all implementing a common API interface but each instance is hosted on different infra with different config.

[dbrgn]

@chris48s correct! 👍🏻