You are viewing Skygear v1 Documentation.Switch to Skygear v0 Documentation

Restful HTTP Endpoint

While you can easily perform the CRUD (Create, Read, Update, Delete) operations by using the SDK directly, you still have the option to implement a custom restful backend using cloud codes. The decorator helps you create the necessary routes for this purpose.

Using the decorator

To implement the restful resource, you need to create a class that inherits one of the Skygear restful classes:

  • skygear.RestfulResource

    Using the RestfulResource class allows you to define the methods shown in the example below, which correspond to the restful endpoints noted in the comments:

    import skygear'/notes')
    class MyNote(skygear.RestfulResource):
        # GET /notes
        def index(self):
            # return list of notes
        # POST /notes
        def create(self):
            payload = self.get_payload()
            # process the payload and save the notes to database
        # DELETE /notes/{id}
        def delete(self, id):
            # delete the item of the given id
        # PUT /notes/{id}
        def update(self, id):
            payload = self.get_payload()
            # process the payload and update the notes in the database
        # GET /notes/{id}
        def get(self, id):

    In the above example, the mapping between the class methods and the HTTP endpoints are:

    class method HTTP request method endpoint description
    index(self) GET /notes list notes
    create(self) POST /notes create a note
    delete(self, id) DELETE /notes/{id} delete the note of given id
    update(self, id) PUT /notes/{id} update the note of given id
    get(self, id) GET /notes/{id} fetch the note of given id


    By default, these endpoints are accessible by anyone, including unauthenticated user. To restrict access to authenticated user, specify the user_required to be True in the decorator. And you can obtain the user ID by skygear.util.context.current_user_id().'/notes', user_required=True)
  • skygear.RestfulRecord

    Using the RestfulRecord class will have the 5 restful API methods shown above implemented for you. By subclassing RestfulRecord, you need to set the class variables record_type and database_id to specify the associated record type and database ID.

    ```python`'/tasks') class RestfulTask(skygear.RestfulRecord): record_type = 'task' database_id = '_public'

    On top of the implemented methods, you can implement
    the custom methods `query_options` and `predicate` to tweak
    the behavior of the listing method `index()`.
    - `query_options` - This method should return a dict containing parameters
      to be sent to the Skygear Server `record:query action`.
    - `predicate` - This method can be used to filter the resources from
      Skygear Server. It should return an array of Skygear query predicates.
    The example below shows the implementation of a restful API with
    pagination support.
    import skygear'/tasks')
    class MyTask(skygear.RestfulRecord):
        record_type = 'task'
        database_id = '_public'
        def query_options(self):
            # /tasks?limit=50&offset=100 will return the 101th to 150th records
            # ordered by the `due_date` field
            return {
                'limit': int(self.request.values.get('limit', 100)),
                'offset': int(self.request.values.get('offset', 0)),
                'sort': [[{'$val': 'due_date', '$type': 'keypath'}, 'asc']],
                'count': True,
        def predicate(self):
            # Only tasks belonged to the "work" `category` will be returned
            return ['eq', {'$type': 'keypath', '$val': 'category'}, 'work']


    The endpoints created with RestfulRecord are subject to the usual access control, i.e.:

    • Only authenticated users can create, update or delete records
    • Access control defined for the records are applied'/notes', user_required=True)