API

This documentation shows you how you can use the htput API in order to create new addresses, update and retrieve content from the addresses you created as well as add subaddresses and append data to existing content.

We will be using curl for demonstration purposes, but you can use any http library of your choice of course.

Creating a new Address

To create a new address you must send a PUT request to the desired address with the content you wish to publish on that address:

curl -X PUT https://htput.com/my-new-address -d "Some content"

If that address is not owned yet, you will get a successful response like the following one:

{"pass":"de8bb18b","status":"ok","message":"Congratulations, your content has been published successfully!"}

However, if the address is already taken, you will get something like this instead:

{"status":"error","error_msg":"Password required!","error_type":"pass_required"}

In this case you should try a different address until you get a successful response.

Retrieving the contents of an address

All data published at htput remains public, so all you have to do is make a GET request to the address:

curl https://htput.com/my-new-address

The output will be:

Some content

Forcing a custom Content-Type

When you make a GET request to an address the response will always have "text/html" as the value of the Content-Type response header. In order to change that you can send a contentType query parameter specifing a different MIME-type string desired. For example:

curl https://htput.com/my-new-address?contentType=image/png

This will allow the browser and other applications to correctly interpret the contents of the requested address, which means you can store other types of documents besides just html pages.

Updating content of an existing address

Even though anybody can see your stuff, only you have the authority to update it, because only you (hopefully) holds the password, which is given to you upon the creation of a new address:

{"pass":"de8bb18b",...

You must then send a PUT request with the HTPUT_PASS header containing that password:

curl -X PUT https://htput.com/my-new-address -d "Updated content" --header "Htput-pass: de8bb18b"

If the password is correct, the content will be updated and you will get a response like this:

{"status":"ok","message":"Content stored successfully!"}

Creating/Updating subaddresses

Once you have become the owner of an address you have also become the owner of all possible subaddresses of this address. This means you can use the same password to push content to urls such as these:

curl -X PUT https://htput.com/my-new-address/subaddress1 -d "Contents of Subaddress" --header "Htput-pass: de8bb18b"
curl -X PUT https://htput.com/my-new-address/another-subaddress -d "Contents of Another Subaddress" --header "Htput-pass: de8bb18b"
curl -X PUT https://htput.com/my-new-address/yet_another -d "More content" --header "Htput-pass: de8bb18b"
curl -X PUT https://htput.com/my-new-address/even_more -d "More stuff" --header "Htput-pass: de8bb18b"

Deleting addresses and subaddresses

To delete an address you must use the DELETE http method along with the Htput-pass header:

curl -X DELETE https://htput.com/my-new-address/even_more --header "Htput-pass: de8bb18b"

The response should be something like:

{"status":"ok","message":"Content deleted successfully"}

ATTENTION: deleting a root address will delete all its subaddresses!!

Appending data

Everytime you PUT something to some address you are actually replacing the existing contents of that address. If you want to add something to the end of the existing content you must use the HTPUT_APPEND header like in the example below:

curl -X PUT https://htput.com/my-new-address -d $'\nNew Line' --header "Htput-append: 1" --header "Htput-pass: de8bb18b"

Now let's fetch the contents of this address to see what's in it:

curl https://htput.com/my-new-address

The output will be:

Updated content
New Line

This is obviously perfect for logging stuff on the fly. Of course, you can use this same feature for appending data to subaddresses as well.

Conclusion

This is not rocket science but surely can be useful to a couple of developers out there.

HTPut

API