Skip to content

How to define recommendation API endpoints

Recommendation endpoint executes corresponding algorithms and serves the result to client applications (web and mobile). At a glance recommendation endpoint is a way to bound particular url to one or many algorithms which produce recommendation according received parameters.

The recommendation endpoints can be also seen as simple analogy to AWS Lambda functions. Basically it is required to implement corresponding function (handler) in the notebook, define endpoint configuration and push it to the GitLab repository. Afterwards Endpoint Scheduler will make updated version available on Recommendation API (the process usually takes around one minute).

Major features include:

  • Custom arguments by URL query params
  • A/B testing based on user, client or session
  • Fallback algorithm to be used in case of error in the main one
  • Recommendation token to evaluate algorithm performance
  • Monitoring and common metrics out of the box
  • Debug flags to troubleshoot issues


To be able to complete this tutorial, you will need to be familiar with PEACH Lab environment.


Endpoints are configured by the same mechanism as tasks using PEACH configuration files. It can be either peach.yaml or any other yaml file inside peach.conf folder in the root of your Git repository.

Let's define a simple function:

def hello_world():
    return 'Hello, world'

To register it as an endpoint the following configuration is required:

codops: default
    url: /hello-world
        notebook: <your_notebook>.ipynb
        method: hello_world

Similar to the tasks it is required to provide the codops, name and url for the endpoint and set of algorithms under components attribute (in most of the cases there will be only one component). For each component required fields are notebook and method

By default only cell with definition of the given method would be imported. If you want the full notebook to be imported - use full_notebook: true setting here

After notebook with algorithm and corresponding configuration is pushed to default branch (usually master, unless you have defined another default branch in Gitlab) of the git repository the endpoint should be deployed and available in couple of minutes.


By default the algorithm code will be executed under Python 2.7. If you want to run it under Python 3 - you can specify this in python_version parameter in peach.conf (see examples in examples)


Requests to endpoints can be made with either GET or POST requests and parameter can be sent via query parameters, headers and for POST request - via body. See examples for details

Next steps

Please, check out corresponding notebook with more detailed examples covering endpoint parametes, A/B tests and fallbacks from tutorials repository here.