Muitas (mas não todas) das operações disponibilizadas na API do UOL Cloud Storage necessitam de autenticação prévia para poderem ser realizadas, em especial aquelas que criam, excluem ou alteram arquivos e configurações do UOL Cloud Storage. Para realizar essa autenticação, uma invocação à API REST do UOL Cloud Storage deve ser realizada por meio de uma requisição HTTPS do tipo GET com o caminho https://api.uolos.com.br/auth/v1.0, tal como demonstrado no exemplo abaixo:
1. Requisição HTTP para a realização da autenticação:
GET https://api.uolos.com.br/auth/v1.0 HTTP/1.1 X-Auth-User: 123abc456:uol X-Auth-Key: xYz890BcD765gHi321
Tal como demonstrado no exemplo, a URL de destino da requisição deve ser https://api.uolos.com.br/auth/v1.0 para o autenticação, além dos cabeçalhos HTTP: X-Auth-User e X-Auth-Key com valores para a chave de acesso (ou Acces Key que terá sempre o sufixo :uol) e a respectiva senha (Secret Key). O valor da chave de acesso e da senha podem ser visualizados na tela de gerenciamento do UOL Cloud Storage. Caso seja necessário, a senha também poderá ser alterada nesta mesma tela.
Alternativamente, para manter compatibilidade com alguns programas clientes, os cabeçalhos HTTP X-Storage-User e X-Storage-Pass podem ser usados em lugar dos cabeçalhos X-Auth-User e X-Auth-Key.
GET https://api.uolos.com.br/auth/v1.0 HTTP/1.1 X-Storage-User: 123abc456:uol X-Storage-Pass: xYz890BcD765gHi321
Após a realização da chamada HTTPS da requisição, uma resposta será recebida tal como no exemplo abaixo:
2. Resposta HTTPS para a realização da autenticação:
HTTP/1.1 200 OK Date: Sun, 01 Set 2013 15:32:21 GMT Content-Type: text/html; charset=UTF-8 Content-Length: 0 Connection: keep-alive Server: UOLOS-1.0.6 X-Storage-Url: https://api.uolos.com.br/v1/UOL_123abc456 X-Auth-Token: UOL_qwe123asd456zxc789ewq321dsa654cxz987 X-Storage-Token: UOL_qwe123asd456zxc789ewq321dsa654cxz987
Tal como demonstrado no exemplo, quando a autenticação é feita com sucesso, um status HTTP 200 é retornado e a resposta conterá os cabeçalhos X-Storage-Url, X-Auth-Token e X-Storage-Token. Qualquer resposta com status 2xx é uma resposta que indica o sucesso da requisição. Um status HTTP 401 é devolvido se a senha estiver incorreta. Um status HTTP 400 é devolvido se a chave de acesso estiver incorreta, mal-formada ou inativa.
Após a etapa de autenticação ser realizada com sucesso, todas as invocações subsequentes devem ser realizadas para a URL e caminhos especificada no cabeçalho X-Storage-Url e devem incluir o cabeçalho X-Auth-Token na requisição com o valor informado na resposta da autenticação. Para manter a compatibilidade com alguns programas clientes, o cabeçalho X-Storage-Token também pode ser utilizado em lugar do cabeçalho X-Auth-Token.
As operações posteriores à etapa de autenticação seriam enviadas para o caminho /v1/UOL_123abc456, da URL api.uolos.com.br, por meio de HTTP. No UOL Cloud Storage o valor do cabeçalho X-Storage-Url sempre será https://api.uolos.com.br/v1/UOL_123abc456. Além disso, cada requisição posterior deverá também enviar o cabeçalho X-Auth-Token (ou alternativamente X-Storage-Token) com o valor informado no cabeçalho X-Auth-Token da resposta da autenticação. É importante observar-se que esse token de autenticação é válido por um período de 24 horas.
Veja, a seguir, alguns exemplos de requisições.
3. Exemplo de uma requisição autenticada para baixar um arquivo:
GET https://api.uolos.com.br/v1/UOL_123abc456/container-exemplo/arquivo-exemplo.txt HTTP/1.1 X-Auth-Token: UOL_qwe123asd456zxc789ewq321dsa654cxz987
Neste exemplo, nota-se que a parte do caminho https://api.uolos.com.br/v1/UOL_123abc456 utilizado na requisição autenticada é extraído do cabeçalho X-Storage-Url. Nota-se também que o cabeçalho X-Auth-Token informado na requisição tem o mesmo valor da resposta do cabeçalho X-Auth-Token recebido na resposta da autenticação.
Caso o container, ou pasta, onde o arquivo se encontra for configurada como público (ver documentação "container público") não e necessário informar o cabeçalho X-Auth-Token, e o protocolo HTTPS é opcional.
GET http://api.uolos.com.br/v1/UOL_123abc456/container-exemplo/arquivo-exemplo.txt HTTP/1.1
ou
GET https://api.uolos.com.br/v1/UOL_123abc456/container-exemplo/arquivo-exemplo.txt HTTP/1.1