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:
@@ -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>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user