Saksbehandlingstiden i forvaltningen

Uma vez que um SW REST implementa uma Resource-Oriented Architecture existe a necessidade de identificar os seus recursos e respetivos URIs de acesso.

A identificação dos recursos tem que ser considerada em conjunto com o formato das URI e dos verbos HTTP disponíveis.

4.2.1 Identificação dos recursos

Na definição dos recursos do serviço web e respetivos URIs foram seguidas as seguintes regras [28]:

1. utilizar domínios e subdomínios para agrupar de forma lógica os recursos;

2. utilizar a forward-slash (/), no segmento do URI, para indicar relação hierárquica entre recursos;

26

3. utilizar a vírgula (,) e o ponto e vírgula (;), no segmento do URI, para indicar uma relação não hierárquica entre elementos;

4. utilizar o hyphen (-) e underscore (_) ou capitalização para melhorar a legibilidade dos nomes, no caso de estes serem longos;

5. utilizar o “e” comercial (&) para separar parâmetros na área do URI reservada à

querystring;

6. evitar a utilização de extensões de ficheiros (e.g.: .php, .aspx,.jsp, etc) nos URIs. Como o serviço web REST é um proxy ONVIF, podemos considerar que os recursos são os serviços das câmaras e respetivos elementos ONVIF. Para NVTs os serviços ONVIF são os seguintes: Device Management, Media, Imaging, PTZ, DeviceIO, Events.

Considerando o prefixo “onvif/” para aceder ao serviço proxy ONVIF (i.e., à aplicação FastCGI) no servidor e os serviços ONVIF como os recursos principais, temos (utilizando a regra 2) o seguinte formato de URI:

/onvif/{serviço_onvif}

e.g: /onvif/media

A utilização do prefixo “onvif/” serve também para melhorar a legibilidade das URIs.

No entanto, esta URI representa um recurso apenas em abstracto, uma vez que as câmaras é que são recursos concretos (também principais) do serviço. Para definir por completo um recurso ONVIF, é necessário fornecer o URI de acesso ao serviço na câmara pretendida, tendo sido adotado o seguinte formato:

/onvif/{serviço_onvif},{endereco_servico_codificado}

Em que:

 {serviço_onvif} pode ser: devicemgmt, media, imaging, ptz, deviceio ou events.

 {endereco_servico_codificado} é o endereço completo da câmara sem protocolo (i.e., sem “http://”) e codificado (url encoded).

A necessidade de, no URI constar o endereço completo da câmara e não apenas o ip:porta, prende-se com o facto dos endereços dos serviços ONVIF variarem de câmara para câmara. Outros aspectos deste formato têm as seguintes razões:

27

 o endereço do serviço na câmara não tem relação hierárquica com o serviço, pois o servidor não conhece as câmaras existentes (daí a utilização da "," como separador).

 a codificação do URI de acesso ao serviço na câmara é necessário, pois o mesmo contém "/" e não pode dar origem a subrecursos.

Por exemplo, para o serviço 208.124.204.172:81/onvif/device_service, o recurso é:

/onvif/devicemgmt,208.124.204.172%3A81%2Fonvif%2Fdevice_service/

4.2.2 Operações sobre os recursos

Para além dos recursos, deverão ser também definidas as operações a serem realizadas sobre esses mesmos recursos. Em REST um pedido GET a um recurso deve devolver a informação desse mesmo recurso, podendo ser um registo único ou uma lista. Para além da informação do recurso, deve também ser devolvida na resposta a informação necessária para a transição de estado. Desta forma, o GET de um dado serviço ONVIF deverá devolver a lista de recursos acessíveis a partir dessa “página”. Exemplificando:

GET /onvif/media,208.124.204.172%3A81%2Fonvif%2Fmedia_service/

devolve a lista de recursos (seus URI) válidos para o serviço media da respetiva câmara. De forma a garantir que o GET de todos os serviços devolve a lista de recursos acessíveis, foi necessário implementar na biblioteca UMOC algumas funções adicionais ao nível dos serviços:

 Imaging – uma função para devolver a lista de video sources disponíveis;

 PTZ – uma função para devolver a lista de media profiles disponíveis;

A biblioteca UMOC abstrai alguns elementos ONVIF e o proxy reflete o mesmo nível de abstração. Os elementos do primeiro nível de cada serviço ONVIF são refletidos nos URIs acrescentando um novo segmento com o separador forward-slash (/), uma vez que existe uma relação hierárquica entre eles e o recurso “serviço ONVIF da câmara”. Por exemplo:

GET /onvif/media,208.124.204.172%3A81%2Fonvif%2Fmedia_service/profiles

devolverá a lista de perfis de media da respectiva câmara.

Assim, para eleger os recursos de cada serviço, empregou-se a seguinte lógica: as funções da biblioteca cujo nome são sujeitos gramaticais são convertidas em recursos.

28

Exemplificando, as operações sobre o recurso ONVIF “users” ficam definidas da seguinte forma (onde {EC} = endereço do serviço codificado):

URI / Recurso Método Descrição

/onvif/ devicemgmt,{EC}/users GET Obtém a lista de utilizadores de um dado dispositivo.

POST Cria um novo utilizador num dado dispositivo.

/onvif/ devicemgmt,{EC}/users/{username} PUT Edita o utilizador com um dado username num dado dispositivo. DELETE Remove o utilizador com um dado

username num dado dispositivo. Tabela 1- Operações sobre o recurso ONVIF users

As funções da biblioteca cujos nomes são verbos (e.g. AbsoluteMove_LL, RelativeMove_LL, ContinuousMove_LL, StopPTZ_LL, moveFocus_LL, stopFocus_LL, goto_HomePosition_LL, StartMulticastStream_LL, StopMulticastStream_LL, etc), são convertidas em parâmetros no corpo de pedidos PUT/POST cuja URI identifica o elemento ONVIF comum a um conjunto de funções. Funções como, por exemplo, StartMulticastStream_LL e StopMulticastStream_LL:

 refletem operações sobre o mesmo recurso ONVIF e têm nomes distintos;

 são verbos e não faz sentido serem recursos, o que também reforça a coerência da regra segundo a qual funções que são sujeitos gramaticais são recursos;

 podem ser abstraídos pelo mesmo recurso, neste caso MulticastStream, sendo os seus comandos convertidos em parâmetros no corpo PUT/POST do pedido.

Desta forma, definiu-se que comandos ONVIF que são “verbos” podem ser abstraídos num mesmo recurso, em que os parâmetros definidos na altura do pedido e enviados no corpo de um pedido PUT/POST definem a função ONVIF a ser executada. Esta unificação de funções que são verbo num recurso permite uma redução da complexidade da API do SW REST. Para as funções exemplificadas anteriormente, o pedido:

PUT/onvif/media,{EC}/profiles/{token}/multicaststream

terá no corpo o comando em formato JSON: {"command":"stop/start"}

O comando aqui exemplificado permite iniciar (StartMulticastStream_LL) ou parar (StopMulticastStream_LL) o multicast stream relativo ao perfil de media identificado pelo seu token. O verbo HTTP utilizado é o PUT, pois estamos a alterar o estado de um recurso existente. O token de um media não é mais do que o seu identificador. Em ONVIF os

29

identificadores dos recursos são do tipo string, o que obriga a que o seu valor surja codificado no URI para garantir desta forma inexistência de caracteres reservados.

É ainda de referir que, na especificação ONVIF existem recursos para os quais não faz sentido fazer um GET (e.g: multicaststream, homeposition, synchronizationpoint), pelo que no serviço web implementado existem recursos apenas com PUT, POST e/ou DELETE. REST é uma filosofia e não uma norma verificável, tendo os seus limites e só podendo ser seguida até certo ponto. Assim, no exemplo apresentado (multicaststream), segundo a especificação ONVIF existem apenas duas operações sobre este recurso: stop e start, não existindo qualquer operação de consulta (GET).

A sistematização das regras adotadas para a definição dos URI do serviço web REST encontram-se no Anexo A.

A lista completa dos recursos definidos para o serviço web REST, bem como as operações a disponíveis sobre os mesmos, encontram-se no Anexo B.