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 }