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
2026-09-27 16:47:30 +01:00
parent 5d8cd38351
commit 71557db37c
21 changed files with 112 additions and 90 deletions
+24 -22
View File
@@ -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>