Welcome to gemstone’s documentation!

The gemstone library aims to provide an easy way to develop simple and scalable microservices by using the asynchronous features of Python.

This library offers support for writing a microservice that:

  • exposes a public Json RPC 2.0 HTTP API (see The JSON RPC 2.0 specifications )
  • can protect API access based on API token identification.
  • can communicate with other microservices through the JSON RPC protocol.
  • can communicate with other microservices through events (messages).

This documentation is structured in multiple parts:

  • Overview - General information to get you started.
  • Topics - A compilation in-depth explanations on various topics of interest.
  • Reference - The reference to the classes, functions, constants that can be used.

See also

Hello world

In a script hello_world.py write the following:

import gemstone

class HelloWorldService(gemstone.MicroService):
    name = "hello_world_service"
    host = "127.0.0.1"
    port = 8000

    @gemstone.exposed_method()
    def say_hello(self, name):
        return "hello {}".format(name)

if __name__ == '__main__':
    service = HelloWorldService()
    service.start()

We have now a microservice that exposes a public method say_hello and returns a "hello {name}".

What we did is the following:

  • declared the class of our microservice by inheriting gemstone.MicroService
  • assigned a name for our service (this is required)
  • assigned the host and the port where the microservice should listen
  • exposed a method by using the gemstone.exposed_method() decorator.
  • after that, when the script is directly executed, we start the service by calling the gemstone.MicroService.start() method.

To run it, run script

python hello_world.py

Now we have the service listening on http://localhost:8000/api (the default configuration for the URL endpoint). In order to test it, you have to do a HTTP POST request to that address with the content:

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d '{"jsonrpc": "2.0","id": 1,"method": "say_hello","params": {"name": "world"}}' \
 'http://localhost:8000/api'

The answer should be

{"result": "hello world", "error": null, "jsonrpc": "2.0", "id": 1}

Table of contents:

Todo

Make this use self.io_loop to resolve the request. The current implementation is blocking and slow

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/gemstone/envs/stable/lib/python3.5/site-packages/gemstone-0.10.1-py3.5.egg/gemstone/core/microservice.py:docstring of gemstone.MicroService.get_service, line 7.)

Indices and tables