github.com/jbking/gohan@v0.0.0-20151217002006-b41ccf1c2a96/docs/source/api.rst (about)

     1  ==============
     2  API
     3  ==============
     4  
     5  In this section, we show how we generate REST API based on schema.
     6  
     7  "$plural", "$singular", "$prefix" and "$id" are read directly from schema,
     8  "$namespace_prefix" is computed using namespace information and might be empty
     9  if schema has no namespace specified.
    10  
    11  Note: An extension computes actual access URL for each resource and substitutes
    12  prefix property with it during schema listing calls. User can list resources
    13  using this URL and access a single instance of resource by prepending "/$id"
    14  suffix.
    15  
    16  List
    17  --------------
    18  
    19  List REST API
    20  
    21  List supports pagination by optional GET query parameters ``sort_key`` and ``sort_order``.
    22  
    23  ================  ==========  =============  ================  ====================================================
    24  Query Parameter   Style       Type           Default           Description
    25  ================  ==========  =============  ================  ====================================================
    26  sort_key          query       xsd:string     id                Sort key for results
    27  sort_order        query       xsd:string     asc               Sort order - allowed values are ``asc`` or ``desc``
    28  limit             query       xsd:int        0                 Specifies maximum number of results.
    29                                                                 Unlimited for non-positive values
    30  offset            query       xsd:int        0                 Specifies number of results to be skipped
    31  <parent>_id       query       xsd:string     N/A               When resources which have a parent are listed,
    32                                                                 <parent>_id can be specified to show only parent's children.
    33  ================  ==========  =============  ================  ====================================================
    34  
    35  When specified query parameters are invalid, server will return HTTP Status Code ``400`` (Bad Request)
    36  with error message explaining the problem.
    37  
    38  To make navigation easier, each ``List`` response contains additional header ``X-Total-Count``
    39  indicating number of all elements without applying ``limit`` or ``offset``.
    40  
    41  Example:
    42  GET http://$GOHAN/[$namespace_prefix/]$prefix/$plural?sort_key=name&limit=2
    43  
    44  Response will be
    45  
    46  HTTP Status Code: 200
    47  
    48  .. code-block:: javascript
    49  
    50    {
    51      "$plural": [
    52         {
    53           "attr1": XX,
    54           "attr2": XX
    55         }
    56      ]
    57    }
    58  
    59  Child resources access
    60  ------------------------
    61  
    62  Child resources can be accessed in two ways:
    63  
    64  Full path
    65    In order to access a child resource in that way, we need to know all it parents.
    66  
    67    e.g. POST http://$GOHAN/[$namespace_prefix/]$prefix/[$ancestor_plural/$ancestor_id/]$plural
    68  
    69  Short path
    70    If we don't know resource full path, it can be accessed with $parent_id.
    71  
    72    e.g. POST http://$GOHAN/[$namespace_prefix/]$prefix/$plural?$parent_id=<parent_id>
    73  
    74  GET
    75  --------------
    76  
    77  Show REST API
    78  
    79  GET http://$GOHAN/[$namespace_prefix/]$prefix/$plural/$id
    80  
    81  Response will be
    82  
    83  HTTP Status Code: 200
    84  
    85  .. code-block:: javascript
    86  
    87    {
    88      "$singular": {
    89        "attr1": XX,
    90        "attr2": XX
    91      }
    92    }
    93  
    94  
    95  CREATE
    96  --------------------------------------
    97  
    98  CREATE Resource REST API
    99  
   100  POST http://$GOHAN/[$namespace_prefix/]$prefix/$plural/
   101  
   102  Input
   103  
   104  Note that input json can only contain
   105  if you set "create" permission for this
   106  
   107  HTTP Status Code: 202
   108  
   109  .. code-block:: javascript
   110  
   111    {
   112      "$singular": {
   113        "attr1": XX,
   114        "attr2": XX
   115      }
   116    }
   117  
   118  
   119  Response will be
   120  
   121  .. code-block:: javascript
   122  
   123    {
   124      "$singular": {
   125        "attr1": XX,
   126        "attr2": XX
   127      }
   128    }
   129  
   130  
   131  Update
   132  --------------------------------------
   133  
   134  Update Resource REST API
   135  
   136  PUT http://$GOHAN/[$namespace_prefix/]$prefix/$plural/$id
   137  
   138  Input
   139  
   140  Note that input json can only contain
   141  if you set "update" permission for this
   142  
   143  .. code-block:: javascript
   144  
   145    {
   146      "$singular": {
   147        "attr1": XX,
   148        "attr2": XX
   149      }
   150    }
   151  
   152  
   153  Response will be
   154  
   155  HTTP Status Code: 200
   156  
   157  .. code-block:: javascript
   158  
   159    {
   160      "$singular": {
   161        "attr1": XX,
   162        "attr2": XX
   163      }
   164    }
   165  
   166  
   167  DELETE
   168  --------------------------------------
   169  
   170  Delete Resource REST API
   171  
   172  HTTP Status Code: 204
   173  
   174  DELETE http://$GOHAN/[$namespace_prefix/]$prefix/$plural/$id
   175  
   176  
   177  Custom Actions
   178  --------------------------------------
   179  
   180  Run custom action on a resource
   181  
   182  POST http://$GOHAN/[$namespace_prefix/]$prefix/$plural/$id/$action_path
   183  
   184  Input
   185  
   186  Input json can only contain parameters defined in input schema definition
   187  It requires "$action" allow policy
   188  
   189  .. code-block:: javascript
   190  
   191    {
   192      "parameter1": XX,
   193      "parameter2": XX
   194    }
   195  
   196  
   197  Response will be
   198  
   199  HTTP Status Code: 200
   200  
   201  .. code-block:: javascript
   202  
   203    {
   204      "output1": XX,
   205      "output2": XX
   206    }