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 http://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 http://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 http://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 http://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 http://htput.com/my-new-address/subaddress1 -d "Contents of Subaddress" --header "Htput-pass: de8bb18b"
curl -X PUT http://htput.com/my-new-address/another-subaddress -d "Contents of Another Subaddress" --header "Htput-pass: de8bb18b"
curl -X PUT http://htput.com/my-new-address/yet_another -d "More content" --header "Htput-pass: de8bb18b"
curl -X PUT http://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 http://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 http://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 http://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.

Making external GET/POST requests

You may already know that it's not possible to use javascript to fetch data from external domains, unless they implement something called CORS. However, htput has a cool feature which allows you to circumvent this problem by offering you a way of proxing GET/POST requests to other websites:

curl http://htput.com/https://some-external-website.com/api?method=etc

This is obviously useful for creating web applications purely in javascript which extracts data from other websites:

$.get("/https://some-external-website.com/",function(response){
   // the "response" var here has the whole webpage content
})

Note: POST, PUT and DELETE methods are also supported by this feature!

Conclusion

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

<ht />ut

API