16 RESTful API ¶

GNU Artanis provides a command art api to generate RESTful API skeleton, and the API version can be managed.

art api -c
creating restful API v1
create app/api/v1.scm

The generated file app/api/v1.scm will contain such a line:

(define-restful-api v1) ; DO NOT REMOVE THIS LINE!!!

v1 is the default version, if you may specify your prefered API version, for example, v3:

art api -c -v v3

-c means to create.

You should use api-define to define the RESTful API:

(api-define rule handler)

api-define is an overloaded method of the controller define function. So you may use it like what you do with the controller in MVC. Here’s a pseudo example:

(define (auth-err)
 (scm->json `((status ,status) (reason "Auth error!"))))
(api-define article/list
 (options #:mime 'json #:with-auth auth-err)
 (lambda (rc) ...))

Although the registered URL is "article/list", the actual API would be "v1/article/list", depends on the specified API version.