Getting started
===============

Using the ``omni.services`` extensions and |kit|'s ``--exec`` command-line option makes it easy to get started with services.
As the service evolves and grows, it might be worth turning the service itself into an Extension so that it is easy to ship and distribute.
Doing so will also give all the power of extensions to services, with the possibilities to set up dependencies on other extensions, install additional Python packages and take advantage of the settings framework.


Basic service
#############

Starting with a very simple "Hello World" Python example:

.. code-block:: python
   :caption: hello_world.py
   :name: hello-world-service-example
   :linenos:

   from omni.services.core import main

   def hello_world():
     return "Hello World!"

   main.register_endpoint("get", "/hello-world", hello_world)

That is all there is needed to write a service.
To run this with |kit| and an HTTP transport:

.. code-block:: bash

   ./kit \
     --exec hello_world.py \
     --enable omni.services.core \
     --enable omni.services.transport.server.http \
     --/exts/omni.kit.registry.nucleus/registries/0/name=kit/services \
     --/exts/omni.kit.registry.nucleus/registries/0/url=https://dw290v42wisod.cloudfront.net/exts/kit/services

By default, an API documentation page is created to list the services exposed, and accessible at ``http://localhost:8011/docs``

It is possible to exercise the API from that webpage by using the ``Try it out`` feature within the different endpoints.

The ``omni.kit.registry.nucleus`` settings make sure that the Omniverse services extensions can be found and downloaded as by default they do not ship with the Kit SDK.

Advanced services
#################

A more involved example is available at the following GitHub Repository: https://github.com/NVIDIA-Omniverse/deep-dive-into-microservices

|kit| ships with several more advanced services and more are available in the extension registry and Omniverse Farm is also fully built using the microservices stack within Omniverse and is made up several different services.
Its code is available from the Omniverse Launcher after which its code can be explored.