CodeIgniter RestServer

[Série RestServer] Criando um RestServer com CodeIgniter – Verbos HTTP

No primeiro artigo da série foi apresentado o RestServer e descrito o processo de instalação e configuração. Nesse segundo artigo vamos falar sobre os verbos HTTP e como implementá-los para a criação de um RestServer.

Os verbos HTTP

Quando utilizamos um restserver precisamos informar qual a ação deve ser executada para a URL requisitada. Para isso temos 5 verbos:

  • POST
  • GET
  • PUT
  • PATCH
  • DELETE

Cada um desses 5 métodos possui uma função específica dentro do CRUD. São elas:

  • POST => criar
  • GET => recuperar
  • PUT => alterar
  • PATCH => alterar
  • DELETE => remover

Tanto PUT quanto PATCH são utilizados para alterar os dados. A diferença entre eles é que o PUT é utilizado quando você quer alterar todas as informações de um registro; já o PATCH é utilizado para fazer uma alteração parcial no registro.

No RestServer que estamos estudando, usamos todos os métodos citados anteriormente, exceto o PATCH.

Os verbos são especificados no cabeçalho HTTP da requisição feita ao restserver e também nos respectivos métodos no controller.

Veja no código a seguir como fica estruturado o controller de um restserver para obter informações de usuários:

<?php
require(APPPATH'.libraries/REST_Controller.php');
 
class Usuarios extends REST_Controller {
 
    function index_get()
    {
        // retorna informações do usuário, com status e/ou erro
    }
 
    function index_put()
    {
        // atualizaos dados do usuário e retorna o status e/ou erro
    }
 
    function index_post()
    {
        // cria um novo usuário e retorna o status e/ou erro
    }
 
    function index_delete()
    {
        // remove o usuário e retorna o status e/ou erro
    }
}

Repare que no código acima os 4 métodos do controller Usuários utilizam o mesmo nome – index – seguidos dos prefixos _get, _put, _post e _delete.

Para acessar esses métodos a partir de requisições feitas através de URLs e cabeçalhos HTTP é muito simples. Considerando que o controller Usuarios esteja dentro de application/controllers/api, a URL de acesso seria a seguinte:

/api/usuarios

Sabemos que no CodeIgniter, quando temos um método index no controller, podemos passar somente a identificação do controller na URL, e isso se aplica no caso do RestServer. Mas pra funcionar por completo é preciso combinar a URL com o verbo HTTP que define a requisição, sendo assim para ser executado o método correto no controller é preciso que seja feita a combinação URL + Verbo HTTP.

Recuperando os dados enviados para o RestServer

O RestServer retorna informações baseado em parâmetros e informações recebidas através da requisição HTTP. Para recuperar as informações enviadas para o RestServer existem 4 métodos:

$this->get()

O método $this->get() é o responsável por obter todos os parâmetros enviados ao RestServer em uma requisição GET. Caso queira obter os dados de um parâmetro específico, basta informar o nome do parâmetro: $this->get(‘id’).

$this->put()

O método $this->put() é o responsável por obter todos os parâmetros enviados ao RestServer em uma requisição PUT. Caso queira obter os dados de um parâmetro específico, basta informar o nome do parâmetro: $this->put(‘id’).

$this->post()

O método $this->post() é o responsável por obter todos os parâmetros enviados ao RestServer em uma requisição POST. Caso queira obter os dados de um parâmetro específico, basta informar o nome do parâmetro: $this->post(‘id’).

$this->delete()

O método $this->delete() é o responsável por obter todos os parâmetros enviados ao RestServer em uma requisição DELETE. Caso queira obter os dados de um parâmetro específico, basta informar o nome do parâmetro: $this->delete(‘id’).

Retornando dados através do RestServer

O RestServer é uma via de mão dupla, onde são enviados e recebidos dados. Já vimos como receber os dados no restserver através dos métodos $this->get(), $this->put(), $this->post() e $this->delete(), e agora vamos ver como retornar os dados a partir do restserver.

Toda requisição a um restserver precisa retornar o seu status, e algumas delas, como uma requisição usando o verbo GET, retorna um conjunto de dados junto com o status da requisição.

Ao construir um restserver com CodeIgniter temos à disposição o método $this->response(), que além de retornar um conjunto de dados quando necessário, também pode retornar o status da requisição.

O conjunto de dados que pode ser retornado no método $this->response() deve ser informado no primeiro parâmetro, como um array:

$dados = array("id"=>1, "nome"=>"Universidade Codeigniter");

$this->response($dados);

O método $this->response() retorna um JSON com os dados passados como primeiro parâmetro, algo como:

[
   {
      "id": 1,
      "name": "John",
      "email": "[email protected]",
      "fact": "Loves coding"
   },
   {
      "id": 2,
      "name": "Jim",
      "email": "[email protected]",
      "fact": "Developed on CodeIgniter"
   },
   {
      "0":
         {
            "hobbies":
               [
                  "guitar",
                  "cycling"
               ]
         },
         "id": 3,
         "name": "Jane",
         "email": "[email protected]",
         "fact": "Lives in the USA"
   }
]

O envio do status da requisição (segundo parâmetro) é opcional, e a library Rest_Controller já possui um conjunto de constantes que representam os códigos de status de requisição HTTP mais utilizados.

HTTP_CONTINUE = 100;
HTTP_SWITCHING_PROTOCOLS = 101;
HTTP_PROCESSING = 102; // RFC2518
HTTP_OK = 200;

HTTP_CREATED = 201;
HTTP_ACCEPTED = 202;
HTTP_NON_AUTHORITATIVE_INFORMATION = 203;

HTTP_NO_CONTENT = 204;
HTTP_RESET_CONTENT = 205;
HTTP_PARTIAL_CONTENT = 206;
HTTP_MULTI_STATUS = 207; // RFC4918
HTTP_ALREADY_REPORTED = 208; // RFC5842
HTTP_IM_USED = 226; // RFC3229

HTTP_MULTIPLE_CHOICES = 300;
HTTP_MOVED_PERMANENTLY = 301;
HTTP_FOUND = 302;
HTTP_SEE_OTHER = 303;

HTTP_NOT_MODIFIED = 304;
HTTP_USE_PROXY = 305;
HTTP_RESERVED = 306;
HTTP_TEMPORARY_REDIRECT = 307;
HTTP_PERMANENTLY_REDIRECT = 308; // RFC7238

HTTP_BAD_REQUEST = 400;

HTTP_UNAUTHORIZED = 401;
HTTP_PAYMENT_REQUIRED = 402;

HTTP_FORBIDDEN = 403;

HTTP_NOT_FOUND = 404;

HTTP_METHOD_NOT_ALLOWED = 405;

HTTP_NOT_ACCEPTABLE = 406;
HTTP_PROXY_AUTHENTICATION_REQUIRED = 407;
HTTP_REQUEST_TIMEOUT = 408;

HTTP_CONFLICT = 409;
HTTP_GONE = 410;
HTTP_LENGTH_REQUIRED = 411;
HTTP_PRECONDITION_FAILED = 412;
HTTP_REQUEST_ENTITY_TOO_LARGE = 413;
HTTP_REQUEST_URI_TOO_LONG = 414;
HTTP_UNSUPPORTED_MEDIA_TYPE = 415;
HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
HTTP_EXPECTATION_FAILED = 417;
HTTP_I_AM_A_TEAPOT = 418; // RFC2324
HTTP_UNPROCESSABLE_ENTITY = 422; // RFC4918
HTTP_LOCKED = 423; // RFC4918
HTTP_FAILED_DEPENDENCY = 424; // RFC4918
HTTP_RESERVED_FOR_WEBDAV_ADVANCED_COLLECTIONS_EXPIRED_PROPOSAL = 425; // RFC2817
HTTP_UPGRADE_REQUIRED = 426; // RFC2817
HTTP_PRECONDITION_REQUIRED = 428; // RFC6585
HTTP_TOO_MANY_REQUESTS = 429; // RFC6585
HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431; // RFC6585

HTTP_INTERNAL_SERVER_ERROR = 500;

HTTP_NOT_IMPLEMENTED = 501;
HTTP_BAD_GATEWAY = 502;
HTTP_SERVICE_UNAVAILABLE = 503;
HTTP_GATEWAY_TIMEOUT = 504;
HTTP_VERSION_NOT_SUPPORTED = 505;
HTTP_VARIANT_ALSO_NEGOTIATES_EXPERIMENTAL = 506; // RFC2295
HTTP_INSUFFICIENT_STORAGE = 507; // RFC4918
HTTP_LOOP_DETECTED = 508; // RFC5842
HTTP_NOT_EXTENDED = 510; // RFC2774
HTTP_NETWORK_AUTHENTICATION_REQUIRED = 511;

Sendo assim, você pode usar tanto o código numérico quanto a constante relacionada ao status da operação.

$dados = array("id"=>1, "nome"=>"Universidade Codeigniter");

$this->response($dados, 200);

Ou

$dados = array("id"=>1, "nome"=>"Universidade Codeigniter");

$this->response($dados, HTTP_OK);

Com esses conhecimentos adquiridos até agora temos condições de começar a criar um RestServer já no próximo artigo, e é exatamente isso que faremos.

Então deixe o seu ambiente preparado, instale um cliente rest, pode ser addon ou mesmo aplicativo, e fique ligado aqui no portal para o lançamento do próximo artigo.

Bons estudos!