rokka is an image service that lets you upload images and retrieve them with different configuration. In order to use it, you have to register, create an organization and then upload images into that organization and define how those images can be output.
To get started you need to understand the concepts of organizations, source images, operations and stacks.
Organizations are the term in which images are bundled together. An organization can be your company, or a page. Access rights and billing is done on a level of organizations.
Source images are the images you upload into an organization in rokka. You should always upload the highest resolution images you have in order for the service to create great images for you. rokka will store metadata with the source image, some of which you can alter. Based on the image and metadata, rokka creates a hash which is then used for all other operations with this image.
Operations are single filters that can be applied to images. An example would be resize, where you can specify a width and height.
Stacks are an ordered collection of operations that have a name with it. A stack is always tied to an organization. You can render images with stacks, where the configured operations are applied to the image in the predefined order. This is the main way you can use rokka to create high quality images, very fast.
rokka is controlled via a REST API. The API allows to manage organizations and stacks and to upload images.
We provide a couple of API clients in popular programming languages, but the REST API is documented, in case you need to build your own client. If you open source a client, please send us a note so that we can list it in the documentation.
You can also play with the API in our Swagger UI directly from the browser.
Before we dive into the API more, you should be aware of versioning. The header Api-Version expects a full number as value, lowest being 1. You should always send the API version header when making requests. The pre built libraries already do that by default, sending the correct header for the version of the API they are using.
If you do not use the version header, rokka will always default to the latest version! In other words: If you don't send the version header, your application might break at any time - you have been warned.
Before you can use the rokka service, you need to register. The rokka API will offer an automated registration, but for now, you need to fill in the online form.
To do so, you need only supply an email address. This call will register you at the service and create an organization for you:
curl -H 'Content-Type: application/json' -X POST 'https://api.rokka.io/users' -d '[
{
"email": "my@email.com",
"organization": "example-organization"
}
]'
The response is a json object with the API-Key in it. In addition this information will be mailed to you, just to be sure. Keep them safe, you will need them for the next steps.