README

REST

这个库允许以简单但结构化的方式提供REST API。该库没有特定的Toba要求，可以独立在其他系统中使用。

创建一个API REST

API REST的定义基于约定，无需指定元数据。

资源定义

所有可以命名的信息都是资源，例如：文档、图像、其他资源的集合、数据库中定义的表等。对于特定项目要发布/共享的资源，应通过一个位于 /proyectos/nombre_proyecto/php/rest/ 目录中的PHP类来指定。例如

php/rest/recurso_personas.php 发布在 http://../rest/personas
php/rest/personas/recurso_personas.php 发布在 http://../rest/personas
php/rest/recurso_deportes.php 发布在 http://../rest/deportes

资源文件必须以 recurso_ 为前缀，例如，对于 personas 资源，必须定义文件 recurso_personas.php。任何未使用此前缀定义的文件，都不会被解释为资源。类的名称本身可以与文件名称不同，库不会考虑它，只是实例化在文件中找到的类。

每个资源的访问都与类中对应的方法相关联，该方法接收URL的动态部分作为参数。例如，对于以下资源，使用 id 作为标识符的参数

    //Equivale a GET /rest/{id}: retorna un recurso puntual
    function get($id) ...
    
    //Equivale a DELETE /rest/{id}: elimina un recurso puntual
    function delete($id) ...
    
    //Equivale a PUT /rest/{id}: modifica parte de los atributos del recuso 
    function put($id) ...

以下是一个完整的 personas 资源示例

<?php
class recurso_personas
{

    function get($id_persona)
    {
        $modelo = new modelo_persona($id_persona);
        $fila = $modelo->get_datos();
        rest::response()->get($fila);        
    }

    function delete($id_persona)
    {
        $modelo = new modelo_persona($id_persona);
        $ok = $modelo->delete();
        $errores = array();
        if (!$ok) {
            rest::response()->not_found();
        } else {
            rest::response()->delete($errores);
        }
    }

    function put($id_persona)
    {
        $datos = rest::request()->get_body_json();
        $modelo = new modelo_persona($id_persona);
        $ok = $modelo->update($datos);
        if (!$ok) {
            rest::response()->not_found();
        } else {
            rest::response()->put();
        }
    }
}

对于需要检索资源集合或为特定资源创建资源的情况，使用后缀 list（表示是关于值列表而不是特定值）

    // Equivale a GET /rest: retorna el recurso como un conjunto
    function get_list() ...
    
    // Equivale a POST /rest: da de alta un nuevo recurso
    function post_list($id) ...

<?php
class recurso_personas
{

    function post_list()
    {
        $datos = rest::request()->get_body_json();
        $nuevo = modelo_persona::insert($datos);
        $fila = array('id' => $nuevo);
        rest::response()->post($fila);
    }

    function get_list()
    {
        $personas = modelo_persona::get_personas($where);
        rest::response()->get($personas);
    }

如果要发送不是JSON或具有特定headers的响应，可以更改视图并按以下方式配置响应

<?php
class recurso_documento
{

    function get_list()
    {
        $pdf = documentos::get_pdf();

        $vista_pdf = new \SIUToba\rest\http\vista_raw(rest::response());
        $vista_pdf->set_content_type("application/pdf");
        rest::app()->set_vista($vista_pdf);

        rest::response()->set_data($pdf);
        rest::response()->set_status(200);
        rest::response()->add_headers(array(
            "Content-Disposition" => "attachment; filename=Mi_documento.pdf"
        ));
    }

子API

该库允许将资源分组在子目录中，最多两个层级，从而可以定义子API并实现更好的语义划分，便于根据情况应用不同的配置。此外，这些子目录充当URL访问的前缀，例如 /personas/deportes/。

例如，一个提供当前用户服务的API可以有以下子划分 admin 和 me。为此，需要创建一个空的目录 /rest/me 和 /rest/admin。如果想要了解当前用户的 mascotas，应在 /rest/me/mascotas/recurso_mascotas.php 中创建一个 mascotas 资源，然后可以通过URL /rest/me/mascotas 访问。如果不使用子API，则更复杂的方法是访问 /rest/usuarios/{usuario_actual}/mascotas。

siu-toba / rest

维护者

详情

README

REST

创建一个API REST

资源定义

子API

相关链接