Defining RESTful HTTP Endpoints

View an HTML endpoint:

var endpoints: { viewChapter: { route: '/book/:bookId/:chapterId', // Use ":name" to indicate dynamic route parameters params: [stallion.pathParam('bookId'), stallion.pathParam('chapterId')], handler: function(bookId, chapterId) { var ctx = {bookId: bookId, chapterId: chapterId}; return myContext.renderTemplate("book-chapter.jinja", ctx); } } }; stallion.registerEndpoints(endpoints); import static io.stallion.Literals.*; public class BooksEndpoints { @GET // HTTP methods, alternatives are @GET, @PUT, @DELETE @Path("/book/:bookId/:chapterId") // A colon indicates named dynamics parameters public String viewChapter(@PathParam Long bookId, @PathParam Long chapterId) { Map ctx = map(val("bookId", bookId), val("chapterId", chapterId)); return TemplateRenderer.instance().renderTemplate("book-chapter.jinja", ctx); } } /// Register the endpoints in the boot function of your plugin public void boot() { EndpointsRegistry.instance().addResource("/api/books", new BooksEndpoints()); }

Simple endpoint to retrieve an object:

var endpoints: { getBook: { route: '/book/:bookId/*', // Use ":name" to indicate dynamic route parameters produces: 'application/json', // By default, "text/html", params: [stallion.pathParam('bookId')], handler: function(bookId) { var book = myContext.dal.books.forId(bookId); if (!book) { stallion.raiseNotFound("Could not find book for id " + bookId); } return book; } } }; @POST // HTTP methods, alternatives are @GET, @PUT, @DELETE @Path("/book/:bookId") // A colon indicates named dynamics parameters @Produces("application/json") public Book getBook(@PathParam Long bookId) { Book book = BooksController.instance().forId(bookId); if (book == null) { throw new NotFoundException("Book not found for id " + bookid); } return book; }

Here is an endpoint with all possible options defined:

var endpoints: { completeRoute: { route: '/book/:bookId/*', // Use ":name" to indicate dynamic route parameters produces: 'application/json', // By default, "text/html", method: "POST", // The HTTP method for this route, default is GET role: 'staff', // 'anon' is the default, and means any non-logged in user can access the page. /* "params" represents parameters extracted from the request and passed to the handler function. The order of arguments in the handler function will be the order defined in this array. */ params: [ stallion.longParam("bookId"), // Take the parameter from the route named bookId stallion.queryParam("previewMode")], // a query string value stallion.bodyParam("newTitle"), // a key/value param from the JSON POST body stallion.mapParam() // The entire POST body as a Map. ], handler: function(bookId, preview, title, extra) { return { bookId: bookId, newTitle: title, extra: extra, previewMode: preview } } } } @POST // HTTP methods, alternatives are @GET, @PUT, @DELETE @Path("/book/:bookId/*slug") // A colon indicates named dynamics parameters @Produces("application/json") // The content-type of the response, return "text/html" for web pages @JsonView(RestrictedViews.Owner.class) // Restricts which fields get serialized to JSON @MinRole(Roles.STAFF) // The minimum role required to view this endpoint, use Roles.ANON for a public endpoint public Object bookRoute(@PathParam Long bookId, @QueryParam Boolean previewMode, @BodyParam("newTitle") String newTitle) { Map data = new HashMap<>(); data.put("bookId", bookId); data.put("newTitle", title); data.put("extra", extra); data.put("previewMode", preview); return data; }