mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-09-28 18:22:05 +00:00
Tidy up use of first person in docs. Since I don't run the only server, referring to "me" in the docs was ambiguous and probably reads oddly to the other server owners.
This commit is contained in:
Ian Renton
@@ -30,7 +30,8 @@
|
||||
"alerts"/"upcoming" page simply query the main spot API on a timer, whereas the spots, map and bands pages
|
||||
combine this approach with using the Server-Sent Events (SSE) endpoint to update live.
|
||||
</li>
|
||||
<li>Let me know if you get stuck, I'm happy to help.</li>
|
||||
<li>If you get stuck, get in touch with Spothole's developers who will be happy to help.
|
||||
</li>
|
||||
</ul>
|
||||
<p>If you're fetching spot data, you're unlikely to need a sub-minute refresh time. For example, Spothole only queries
|
||||
the POTA API once every two minutes, so if your client is interested in POTA data there's no need to poll Spothole
|
||||
@@ -43,9 +44,9 @@
|
||||
</p>
|
||||
<p>Remember, here at Spothole Inc. we offer an industry-standard "five nines" uptime on our server, with our own unique
|
||||
twist: we don't tell you which side of the decimal point the nines start! (Translation: This is a hobby project.
|
||||
<code>spothole.app</code> runs on the same server as my blog and other stuff. It might go down without warning. By
|
||||
all means base your own project on data from the main server if you like, but if you want any control over
|
||||
reliability and downtime, please run your own copy instead.)</p>
|
||||
<code>spothole.app</code> runs on the same server a Minecraft server and all sorts of other stuff. It might go down
|
||||
without warning. By all means base your own project on data from the main server if you like, but if you want any
|
||||
control over reliability and downtime, please run your own copy instead.)</p>
|
||||
|
||||
<h3 class="mt-4" id="submitting-spots">Submitting Spots</h3>
|
||||
<p>As well as reading data, clients can submit new spots to Spothole using the "add spot" API endpoint, e.g.
|
||||
@@ -53,45 +54,46 @@
|
||||
to other services such as the DX cluster. Check the <code>spot_allowed</code> and
|
||||
<code>spot_submit_providers</code> fields in the "options" API response to see what the server allows.</p>
|
||||
<p>To stop bots and spammers abusing the spotting function, a Spothole server can be configured to protect against this,
|
||||
which means you will need an <strong>API key</strong>. API keys are issued by the operator of each Spothole server,
|
||||
so get in touch with the server owner and let them know what your software is and how it will use the API. Once you
|
||||
have a key, send it in the <code>X-API-Key</code> header of each add spot request. For example:</p>
|
||||
which means you will need an <strong>API key</strong>. API keys are issued by the owner of each Spothole server,
|
||||
not by the Spothole developer. This server is run by <strong>{{ server_owner_callsign }}</strong>, so get in touch
|
||||
with them and let them know what your software is and how it will use the API. Once you have a key, send it in the
|
||||
<code>X-API-Key</code> header of each add spot request. For example:</p>
|
||||
<pre><code>curl --request POST \
|
||||
--header "Content-Type: application/json" \
|
||||
--header "X-API-Key: your-api-key-here" \
|
||||
--data '{"spot":{"dx_call":"M0TRT","time":1760019539,"freq":14200000,"de_call":"M0TRT"}}' \
|
||||
https://spothole.app/api/v3/spot</code></pre>
|
||||
<p>Your API key identifies your software, so please keep it private. Don't commit it to a public code repository, and
|
||||
don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server operator
|
||||
don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server owner
|
||||
can revoke it, and spot submission from your client will stop working. Servers that don't protect spot submission
|
||||
don't need an API key, and will accept spots with or without one.</p>
|
||||
|
||||
<h3 class="mt-4" id="terms">Conditions of Use</h3>
|
||||
<p>There are some simple, hopefully not onerous terms and conditions that you should agree to before writing a client
|
||||
for the Spothole API. These probably aren't legally binding, and I'm just a random guy on the internet, I'm not
|
||||
going to sue you for breaching them. But having these conditions in place ensures Spothole can continue to operate
|
||||
without me burning out and with no payment required. In the collaborative and respectful tradition of amateur radio,
|
||||
please read and understand them.</p>
|
||||
<p>The conditions are simple, and hopefully not onerous. They probably aren't legally binding, and nobody is likely to
|
||||
sue you for breaching them. But having them in place ensures Spothole can continue to operate without the people
|
||||
running it burning out, and with no payment required. In the collaborative and respectful tradition of amateur
|
||||
radio, please read and understand them.</p>
|
||||
<p>When creating a Spothole client, you agree that:</p>
|
||||
<ul>
|
||||
<li>If you got an AI to write your code, and you run into problems, you will try to understand the code using your
|
||||
Actual Intelligence before asking me for help. If you don't understand the code, please ask the AI to fix it,
|
||||
not me.
|
||||
Actual Intelligence before asking the developer or server owner for help. If you don't understand the code,
|
||||
please ask the AI to fix it, not them.
|
||||
</li>
|
||||
<li>When querying the API, you will send a useful referrer or user agent string that will help me uniquely identify
|
||||
your software. This will allow me to diagnose the problem and figure out who to talk to if Spothole starts
|
||||
receiving too many, or malformed, requests.
|
||||
<li>When querying the API, you will send a useful referrer or user agent string that will help the server owner
|
||||
uniquely identify your software. If their server starts receiving too many, or malformed, requests, this will
|
||||
allow them to diagnose the problem and figure out who to talk to about it.
|
||||
</li>
|
||||
<li>You set a sensible query rate and will not try to take down the server by bombarding it with tons of requests.
|
||||
</li>
|
||||
<li>You are OK with the server being down occasionally. There is no uptime guarantee. This is a hobby project and
|
||||
sometimes I will accidentally break stuff.
|
||||
sometimes stuff will accidentally break.
|
||||
</li>
|
||||
<li>You check for API changes occasionally, e.g. using <a
|
||||
href="https://git.ianrenton.com/ian/spothole/releases.rss">the RSS feed for Spothole release
|
||||
notifications</a>, or by <a href="https://mastodon.radio/@ian">following me on Mastodon</a>, or just by checking
|
||||
back on the Spothole documentation every so often. I will do my best to stop updates breaking older client code,
|
||||
but eventually I will need to turn off old versions of the API for my own sanity.
|
||||
notifications</a>, or by <a href="https://mastodon.radio/@ian">following Spothole's developer on
|
||||
Mastodon</a>, or just by checking back on the Spothole documentation every so often. Every effort is made to stop
|
||||
updates breaking older client code, but eventually old versions of the API will need to be turned off for the
|
||||
developer's sanity.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
@@ -8,11 +8,12 @@
|
||||
<p>The source code can be found at <a href="https://git.ianrenton.com/ian/spothole">https://git.ianrenton.com/ian/spothole</a>.
|
||||
</p>
|
||||
|
||||
<p>I'm sorry this isn't on GitHub. There's too much noise on there now it's been given over to Copilot agents. If you
|
||||
want to contribute code changes, that unfortunately means you'll have to sign up for an account on my Forgejo
|
||||
server (linked above), or email me patch files the old-fashioned way. I'd hoped that Forgejo federation would be
|
||||
working soon, so that at least you could use a Codeberg account rather than a new login specifically for my
|
||||
instance, but unfortunately we're still waiting on that one!</p>
|
||||
<p>Sorry this isn't on GitHub. There's too much noise on there now it's been given over to Copilot agents. If you
|
||||
want to contribute code changes, that unfortunately means you'll have to sign up for an account on the developer's
|
||||
Forgejo server (linked above), or email patch files to <a href="https://ianrenton.com">Ian, M0TRT</a> the
|
||||
old-fashioned way. The hope was that Forgejo federation would be working soon, so that at least you could use a
|
||||
Codeberg account rather than a new login specifically for that instance, but unfortunately we're still waiting on
|
||||
that one!</p>
|
||||
|
||||
<h3 class="mt-4">Code structure</h3>
|
||||
<p>To navigate your way around the source code, this list may help.</p>
|
||||
@@ -99,7 +100,7 @@
|
||||
<p>Finally, simply add the appropriate config to the <code>spot_providers</code> section of <code>config.yml</code>, and
|
||||
your provider should be
|
||||
instantiated on startup.</p>
|
||||
<p>The same approach as above is also used for alerts, and other types of providers. Give me a shout if you need any
|
||||
advice.</p>
|
||||
<p>The same approach as above is also used for alerts, and other types of providers. Give Spothole's developers a shout
|
||||
if you need any advice.</p>
|
||||
|
||||
{% end %}
|
||||
|
||||
@@ -85,8 +85,8 @@
|
||||
}
|
||||
</code></pre>
|
||||
<p>One further change you might want to make to the file above is the <code>add_header
|
||||
Access-Control-Allow-Origin</code> statements. These are what's used on my own Spothole server to make sure that
|
||||
other third-party web-based software can get the data from my instance, and applies to any endpoint underneath
|
||||
Access-Control-Allow-Origin</code> statements. These are what's used on the main <code>spothole.app</code> server to make
|
||||
sure that other third-party web-based software can get the data from that instance, and applies to any endpoint underneath
|
||||
<code>/api</code>. If you want <em>your</em> Spothole instance to be set up the same way, so that others can write
|
||||
software in JavaScript that can access it, leave this intact. But if you want your Spothole instance to only be
|
||||
usable by scripts running on the web server you write, you can remove these lines. (Note that this doesn't stop
|
||||
|
||||
@@ -27,9 +27,9 @@ cp config-example.yml config.yml
|
||||
<p><code>config.yml</code> has an entry for a Clublog API key. If provided, this will allow Spothole to retrieve some
|
||||
more information about DX spots. The software will work just fine without it, but you may find a few country flags
|
||||
etc. are less accurate or missing. Clublog API keys are free, but you'll need to get your own by submitting a
|
||||
helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by my
|
||||
Spothole server, so unless you change the source code of yours to radically increase the rate of querying Clublog,
|
||||
I'm sure they will be fine with your server too.</p>
|
||||
helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by the
|
||||
main <code>spothole.app</code> server, so unless you change the source code of yours to radically increase the rate
|
||||
of querying Clublog, they should be fine with your server too.</p>
|
||||
<p>If your server is public and allows spots to be submitted, you may want to protect it from bots and spammers by
|
||||
setting <code>protect_spot_submission</code> to <code>true</code> and setting the reCAPTCHA keys in
|
||||
<code>config.yml</code>. Users of the web interface will then need to solve a CAPTCHA to submit a spot. Third-party
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
<p>As well as a web interface and an HTTP API, Spothole offers a telnet server. This can be used to integrate Spothole's
|
||||
data into a traditional desktop logging program. The data Spothole produces is compatible with DXSpider, and
|
||||
therefore many loggers should accept it with no problems.</p>
|
||||
<p>This is a relatively new feature however, so if you run into problems, please do let me know.</p>
|
||||
<p>This is a relatively new feature however, so if you run into problems, please let Spothole's developers know.</p>
|
||||
<p>The one caveat with the Spothole telnet server is that <em>it does not support any commands</em>, other than
|
||||
<code>exit</code> or <code>bye</code>.
|
||||
You cannot therefore issue commands to retrieve past entries, set up filters, etc. If you need to filter the data,
|
||||
|
||||
Reference in New Issue
Block a user