Sirvy: Kirby Services API Plugin

For the past few projects I’ve worked on, I have been doing things like cropping/resizing images via url endpoints (like in the early 2.3 beta) and returning page objects as json. This plugin adds a route to your site that lets you create APIs that do things like this very easily.

Check out the repository for full overview and documentation, but in a gist:

Services

The Sirvy plugin provides 3 simple services (by default):

json

returns page contents as json:

/sirvy/home?service=json

resize

returns a resized thumbnail:

/sirvy/home?service=resize&image=image.jpg&width=400

crop

returns a cropped thumbnail:

/sirvy/home?service=crop&image=image.jpg&width=200&height=300

However, you can easily edit these services or write your own to cover any functionality you need from your API!

Page Method

A Sirvy page method is exposed to make generating endpoint URLs super simple from within your templates:

page('home')->sirvy('json');
// -> http://yourkirby.com/sirvy/home?service=json

This is great for spitting out many thumbnails without blocking initial page render:

foreach ($hundredsOfImages as $i) {
  echo '<img src="' . $page->sirvy('resize', [
    'image' => $i->filename(),
    'width' => 500
  ]) . '">';
}


Hopefully someone will find this handy!

9 Likes

Very simple but very powerful! I took a look at the source code. Very awesome!

But as you write in the README, authentication and rate limiting would be great here. Maybe the services could define whether they require authentication (with a specified user role) and how many requests per visitor are allowed?

1 Like

Thanks!

And agreed regarding auth/rate limits, especially for services that are manipulating images. I like the idea of specifying auth/limits on a per service basis. Will look into this.

Also looking into adding a cache option on a per service basis. That way you could cache a json partial, for example.

1 Like

I’ve just pushed an update which adds a caching option for services. This is great if you want to cache a json partial or snippets of html. To use it, just add a cache param to your Sirvy call:

/sirvy/home?service=json&cache=1

By default the items will never expire, but you can adjust that with an option. All items are also always flushed when making content changes in the panel. You can read a little more in the repository.

p.s. I’ve also added json error responses (status code 400) for when Sirvy encounters errors.

2 Likes