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 skygear.rest 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
  
  @skygear.rest('/notes')
  class MyNote(skygear.RestfulResource):
  
      # GET /notes
      def index(self):
          # return list of notes
          pass
  
      # 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
          pass
  
      # 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):
          pass
  

  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

  Caution:

  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().

  @skygear.rest('/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` @skygear.rest('/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.
  
  ```python
  import skygear
  
  @skygear.rest('/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']
  

  Note:

  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

  @skygear.rest('/notes', user_required=True)