The API
Getting an Auth Key
To generate an authentication key, you have to go to autocompeter.com and sign in using GitHub.
Once you've done that you get access to a form where you can type in your domain name and generate a key. Copy-n-paste that somewhere secure and use when you access private API endpoints.
Every Auth Key belongs to one single domain.
E.g. yoursecurekey->www.peterbe.com
.
Submitting titles
You have to submit one title at a time. (This might change in the near future)
You'll need an Auth Key, a title, a URL, optionally a popularity number and optionally a group for access control..
The URL you need to do a HTTP POST to is:
https://autocompeter.com/v1
The Auth Key needs to be set as a HTTP header called Auth-Key
.
The parameters need to be sent as application/x-www-form-urlencoded
.
The keys you need to send are:
Key | Required | Example |
---|---|---|
title |
Yes | A blog post example |
url |
Yes | http://www.example.com/page.html |
group |
No | loggedin |
popularity |
No | 105 |
Here's an example using curl
:
curl -X POST -H "Auth-Key: yoursecurekey"
-d url=http://www.example.com/page.html \
-d title="A blog post example" \
-d group="loggedin" \
-d popularity="105" \
https://autocompeter.com/v1
Here's the same example using Python requests:
response = requests.post(
'https://autocompeter.com/v1',
data={
'title': 'A blog post example',
'url': 'http://www.example.com/page.html',
'group': 'loggedin',
'popularity': 105
},
headers={
'Auth-Key': 'yoursecurekey'
}
)
assert response.status_code == 201
The response code will always be 201
and the response content will be
application/json
that simple looks like this:
{"message": "OK"}
Uniqueness of the URL
You can submit two "documents" that have the same title but you can not submit two documents that have the same URL. If you submit:
curl -X POST -H "Auth-Key: yoursecurekey" \
-d url=http://www.example.com/page.html \
-d title="This is the first title" \
https://autocompeter.com/v1
# now the same URL, different title
curl -X POST -H "Auth-Key: yoursecurekey" \
-d url=http://www.example.com/page.html \
-d title="A different title the second time" \
https://autocompeter.com/v1
Then, the first title will be overwritten and replaced with the second title.
About the popularity
If you omit the popularity
key, it's the same as sending it as 0
.
The search will always be sorted by the popularity
and the higher the number
the higher the document title will appear in the search results.
If you don't really have the concept of ranking your titles by a popularity or hits or score or anything like that, then use the titles "date" so that the most recent ones have higher priority. That way more fresh titles appear first.
About the groups and access control and privacy
Suppose your site visitors should see different things depending how they're signed in. Well, first of all you can't do it on per-user basis.
However, suppose you have a set of titles for all visitors of the site
and some extra just for people who are signed in, then you can use group
as a parameter per title.
Note: There is no way to securely protect this information. You can make it so that restricted titles don't appear to people who shouldn't see it but it's impossible to prevent people from manually querying by a specific group on the command line for example.
Note that you can have multiple groups. For example, the titles that is
publically available you submit with no group
set (or leave it as
an empty string) and then you submit some as group="private"
and some
as group="admins"
.
How to delete a title/URL
If a URL hasn't changed by the title has, you can simply submit it again. Or if neither the title or the URL has changed but the popularity has changed you can simply submit it again.
However, suppose a title needs to be remove you send a HTTP DELETE. Send it to the same URL you use to submit a title. E.g.
curl -X DELETE -H "Auth-Key: yoursecurekey" \
https://autocompeter.com/v1?url=http%3A//www.example.com/page.html
Note that you can't use application/x-www-form-urlencoded
with HTTP DELETE.
So you have to put the ?url=...
into the URL.
Note also that in this example the url
is URL encoded. The :
becomes %3A
.
How to remove all your documents
You can start over and flush all the documents you have sent it by doing
a HTTP DELETE request to the url /v1/flush
. Like this:
curl -X DELETE -H "Auth-Key: yoursecurekey" \
https://autocompeter.com/v1/flush
This will reset the counts all related to your domain. The only thing that isn't removed is your auth key.
Bulk upload
Instead of submitting one "document" at a time you can instead send in a whole big JSON blob. The struct needs to be like this example:
{
"documents": [
{
"url": "http://example.com/page1",
"title": "Page One"
},
{
"url": "http://example.com/page2",
"title": "Other page",
"popularity": 123
},
{
"url": "http://example.com/page3",
"title": "Last page",
"group": "admins"
},
]
}
Note that the popularity
and the group
keys are optional. Each
dictionary in the array called documents
needs to have a url
and title
.
The endpoint to use https://autocompeter.com/v1/bulk
and you need to do a
HTTP POST or a HTTP PUT.
Here's an example using curl:
curl -X POST -H "Auth-Key: 3b14d7c280bf525b779d0a01c601fe44" \
-d '{"documents": [{"url":"/url", "title":"My Title", "popularity":1001}]}' \
https://autocompeter.com/v1/bulk
And here's an example using Python requests:
import json
import requests
documents = [
{
'url': '/some/page',
'title': 'Some title',
'popularity': 10
},
{
'url': '/other/page',
'title': 'Other title',
},
{
'url': '/private/page',
'title': 'Other private page',
'group': 'private'
},
]
print requests.post(
'https://autocompeter.com/v1/bulk',
data=json.dumps({'documents': documents}),
headers={
'Auth-Key': '3b14d7c280bf525b779d0a01c601fe44',
}
)