REST Resources

Search
Feedback

The REST resource URL for a given type corresponds to the name of that type, i.e. the type File corresponds to the /files resource. Structr implements a “best guess” strategy to map singular type names to plural resource URLs, however, the best guess is not always the correct one. The following examples illustrate this strategy:

Good type names (TM) are upper camel-case type names that do not end with a single letter “s”. (This means that two “s” are ok, since Structr will not append a third “s” to the end of the resource URL).








Type nameResource URL
File/files
User/users
MailTemplate/mail_templates
Entry/entries
Access/access

Not-so-good type names (TM) are all uppercase names (like URL, see below why), or names that end with a single “s”, because the best-guess strategy does not handle that case very well. Also the word “series” is not handled correctly by the current implementation, so please be aware. (Sorry!)






Type nameResource URL
Series/sery
URL/u_r_l
Hippopotamus/hippopotamuss

The first example shows how to use curl to access an empty REST resource for a given type, in this case the resource for the built-in type File. Please note that you have to supply a username and a password, otherwise you will only see objects that have intentionally been made public.

$ curl -si -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/files

As you can see, the server responds with a JSON result object containing zero results:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=16oi7uxv9x8mh1mik2p2lapb1l;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding, User-Agent
Transfer-Encoding: chunked
Server: Jetty(9.1.3.v20140225)

{
   "query_time": "0.002825731",
   "result_count": 0,
   "result": [],
   "serialization_time": "0.000088917"
}

In the second example, we will create a File using the POST verb and examine the result.

$ curl -si -HX-User:admin -HX-Password:admin -XPOST http://localhost:8082/structr/rest/files -d '{ "name": "myfile.txt", "contentType": "text/plain" }'

and the server will respond with something like this:

HTTP/1.1 201 Created
Set-Cookie: JSESSIONID=w214ue6bmsb01aje3k60oy41r;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=UTF-8
Location: http://localhost:8082/structr/rest/files/559271b86c9a43efa9ebfb94eedc7b96
Vary: Accept-Encoding, User-Agent
Content-Length: 0
Server: Jetty(9.1.3.v20140225)

Issuing a GET request again, we can now see that the files resource contains one element.

$ curl -si -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/files

Response:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=7rf5rzj4vi3v508vt09izvg1;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding, User-Agent
Transfer-Encoding: chunked
Server: Jetty(9.1.3.v20140225)

{
   "query_time": "0.003137433",
   "result_count": 1,
   "result": [
      {
         "type": "File",
         "name": "myfile.txt",
         "contentType": "text/plain",
         "size": null,
         "url": null,
         "owner": {
            "type": "User",
            "name": "admin",
            "salutation": null,
            "firstName": null,
            "middleNameOrInitial": null,
            "lastName": null,
            "id": "f02e59a47dc9492da3e6cb7fb6b3ac25"
         },
         "path": "/myfile.txt",
         "id": "559271b86c9a43efa9ebfb94eedc7b96"
      }
   ],
   "serialization_time": "0.000332605"
}

Now we can of course modify the entity as well, using the PUT verb on the element resource that contains the newly created file.

$ curl -si -HX-User:admin -HX-Password:admin -XPUT http://localhost:8082/structr/rest/files/559271b86c9a43efa9ebfb94eedc7b96 -d '{ "name": "renamed.txt" }'

and the server responds with:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=1sajlbgesemsizw0c8uhfc9l;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 0
Server: Jetty(9.1.3.v20140225)

Now we access the element resource that contains only the modified element by addressing the nested resource directly.

$ curl -si -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/files/559271b86c9a43efa9ebfb94eedc7b96

Note that the result in the JSON document is not an array since we’re accessing the element directly using its UUID:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=tdojo6jg7cfr934ifv0ni527;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding, User-Agent
Transfer-Encoding: chunked
Server: Jetty(9.1.3.v20140225)

{
   "query_time": "0.003190386",
   "result_count": 1,
   "result": {
      "type": "File",
      "name": "renamed.txt",
      "contentType": "text/plain",
      "size": null,
      "url": null,
      "owner": {
         "type": "User",
         "name": "admin",
         "salutation": null,
         "firstName": null,
         "middleNameOrInitial": null,
         "lastName": null,
         "id": "f02e59a47dc9492da3e6cb7fb6b3ac25"
      },
      "path": "/renamed.txt",
      "id": "559271b86c9a43efa9ebfb94eedc7b96"
   },
   "serialization_time": "0.000341750"
}

And finally, to complete this tiny REST introduction, we use the DELETE verb to remove the file we just created.

$ curl -si -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/files/559271b86c9a43efa9ebfb94eedc7b96 -XDELETE

Response:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=1icahpgj3n675ryac3psjm47;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 0
Server: Jetty(9.1.3.v20140225)

And we can see that the collection resource again contains zero elements.

$ curl -si -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/files

Response:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=gem2ldhtdeaxv8xllnn2j89c;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding, User-Agent
Transfer-Encoding: chunked
Server: Jetty(9.1.3.v20140225)

{
   "query_time": "0.003196869",
   "result_count": 0,
   "result": [],
   "serialization_time": "0.000030503"
}

Direct access to the element resource results in a 404 Not Found error:

$ curl -i --silent -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/files/559271b86c9a43efa9ebfb94eedc7b96

Response:

HTTP/1.1 404 Not Found
Set-Cookie: JSESSIONID=vwguwkl9ekxvjuzbhwg1mwy0;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Length: 18
Server: Jetty(9.1.3.v20140225)

{
  "code": 404
}

Structr comes with a powerful REST backend that automatically creates REST resources for each known type. You can use these resources to manage your data, and even do complex queries on it, i.e. exact / inexact search, range expressions, etc. Data validation happens on the server-side as well, and the server will return the HTTP status code 422 Unprocessable Entity together with a meaningful JSON error message that you can parse in your application if a validation error occurs.

The following sections illustrate the basic use of the Structr REST backend with curl. We will access an empty REST resource, create a new entity, modify it, and eventually delete it. We assume that you have a Structr server running on your local machine with the default port and REST path, which is 8082 and /structr/rest.

Graph-Browser

About this article
Last change 2016-03-04
Topics Structr 2.0