NAV Navbar
csharp python
  • Introduction
  • Get Started Quick
  • Creating Jobs
  • Security
  • Coherence's Infrastructure
  • Errors
  • Introduction

    A quick example:

    using System;
    using CoherenceApi;
    
    public class Program
    {
        public static async Task Main(string[] args)
        {
            Coherence.SetApiToken("my-api-token");
    
            // Prints the sum of all numbers 1 - 100.
            // The sum is computed on Coherence servers.
            var sum = await Coherence.RunAsync(() => Enumerable.Range(1,100).Sum());
            Console.WriteLine(sum);
        }
    }
    
    from coherence import coherence
    
    coherence.set_api_key("my-api-key")
    
    # Prints the sum of all numbers 1 - 100.
    # The sum is computed on Coherence servers.
    sum = coherence.run(lambda: sum(range(1,100)))
    print(sum)
    

    Welcome to Coherence API. Our API provides the ability to run your function on a server in the easiest way possible. For the best experience, it is required that you use the provided client libraries for your language.

    We currently support:

    Due to the nature of our API, other versions of the same platforms are not likely to work. We are working hard on launching support for:

    You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Get Started Quick

    Use the tabs above to select your programming language.

    Coherence API allows you to create jobs on our servers the same way you run a function in your language of choice. It's designed to make developers lives easier.

    Install

    To install the Coherence library, open a shell, go to your project directory and type:

    dotnet add package Coherence.NET
    
    pip install coherenceapi
    

    Install the Coherence client library for your language of choice.

    These libraries are currently required to run jobs on Coherence API.

    Get Your API Key

    You can sign up for your Coherence API key. This key is required to authenticate and start creating jobs.

    Run "Hello World"

    To create your first job, use this code:

    using System;
    using Coherence;
    
    public class Program
    {
        public static async Task Main(string[] args)
        {
            var coherence = new CoherenceApi("my-api-key");
            Console.WriteLine(
              await coherence.Run(() => "Hello World"));
        }
    }
    
    from coherence import coherence
    
    coherence.set_api_key("my-api-key")
    print(coherence.run(lambda: 'hello world'))
    

    Make sure to replace my-api-key with your API key.

    When you run a job on Coherence API, it's return value will be serialized and delivered back to the original calling code. This is useful because you can design jobs to do some work and then return necessary data.

    In this case we are running a job that only returns a string "Hello World", blocking until it returns, and then printing the return value.

    Creating Jobs

    The first time you create a job in an app, there will be a slight delay. We need to upload files and other data about your application so we can recreate it in a secure environment on our servers. All jobs after the first one in an app will run with low latency.

    If you stop your app, but make no changes to it, there won't be another delay. Your application will be cached as long as it remains in use for 7 days. If an application goes 7 days without use, we will remove it from our cache. This only means that the next time you create a job, you'll incur a delay as we set up the application.

    Instant Jobs

    Send users an email after registering.

    // This is a snippet from an ASP.NET Core Website with custom registration
    
    [HttpPost("register")]
    public JsonResult Register([FromBody] RegistrationData registrationData)
    {
        var user = ValidateAndAddUserToDb(registrationData);
    
        var subject = "Hello new user!";
        var html = RenderEmailTemplate('user/hello.html');
    
        var api = new CoherenceApi("my-api-key");
        api.Run(() => EmailSender.SendEmail(user.email, subject, html));
    
        return JsonResult("success");
    }
    
    
    from coherence import coherence
    
    # app here is a Flask instance
    # Flask is a popular micro web framework
    @app.route('/register', methods=['POST'])
    def register():
        user = validate_and_add_user_to_db(request.form)
    
        subject = "Hello new user!"
        html = render_template('user/hello.html')
    
        coherence.set_api_key("my-api-key")
        coherence.run(lambda: send_email(user.email, subject, html), blocking=False)
    
        return redirect('/app')
    

    Instant jobs are the most common form.

    These will run instantly and return their return values back to the original caller in your code. For example, you could use an instant job to send an email to a user who just registered, or to perform compression on their profile picture.

    After an instant job is created, it will be visible on the web dashboard. From there you can view its status and any error details. Unfortunately output logs are not yet available. Send us an email if this is a priority for you.

    Recurring Jobs

    Set up a job to send weekly reminder emails:

    using System;
    using Coherence;
    using MyEmailSender;
    
    public class Program
    {
        public static async Task Main(string[] args)
        {
            var coherence = new CoherenceApi("my-api-key");
    
            // A cron expression to send a reminder every monday at midnight
            var schedule = "0 0 0 * * 1";
    
            // The returned jobId can be used to find the job on the web dashboard.
            var jobId = await coherence.RunRecurring(schedule,
              () => MyEmailSender.SendReminder("[email protected]"));
    
            // Or to cancel the job.
            coherence.CancelRecurring(jobId);
        }
    }
    
    from coherence import coherence
    from myEmailSender import sendReminder
    
    coherence.set_api_key("my-api-key")
    
    # A cron expression to send a reminder every monday at midnight
    schedule = "0 0 0 * * 1";
    
    # The returned jobId can be used to find the job on the web dashboard.
    job_id = coherence.run_recurring(schedule,
        lambda: sendReminder("[email protected]"))
    
    # Or to cancel the job.
    coherence.cancel_recurring(job_id);
    

    6-Part Cron Expression Format

    * * * * * *
    - - - - - -
    | | | | | |
    | | | | | +--- day of week (0 - 6) (Sunday=0)
    | | | | +----- month (1 - 12)
    | | | +------- day of month (1 - 31)
    | | +--------- hour (0 - 23)
    | +----------- min (0 - 59)
    +------------- sec (0 - 59)
    

    Recurring Jobs can be scheduled using a 6-part cron expression. A 6-part cron expression contains a field for seconds at the beginning.

    After a recurring job is created, it will be visible on the web dashboard. From there you can view its status, the status of individual runs, and cancel any future runs.

    Read more about cron expressions.

    Limitations

    The lambda expression you pass to the Coherence library is not executed in any way on your local machine. It is serialized and sent to Coherence servers for evaluation.

    This means that any arguments passed to a function called inside the lambda will not be evaluated before being serialized. Keep this in mind, as sending complex objects over the network can be costly.

    Serialization has its limits as well, and its possible your expression may not be able to be serialized. For this reason its best to keep the passed expression simple and call functions with more complex logic.

    Security

    We take security very seriously at Coherence, and dedicate regular to ensuring the integrity and safety of our systems.

    Your code is executed in an isolated, sandboxed environment. We use containers with tools like SELinux and custom seccomp profiles to further reinforce the sandbox.

    We have security minded-architecture, which aims to dramatically limit the damage of any successful breach. For example, a container escape cannot lead to the exfiltration of another user's data.

    If you have any questions or concerns, drop us an email at [email protected]

    Coherence's Infrastructure

    Coherence's infrastructure is built on hardened OS images on AWS EC2 in the us-east-1 region.

    Errors

    Coherence API is recreating the original execution context of your program, with limited information from inside that program. Certain types of programs may not work correctly for this reason. For example, a projects which have native components, that are compiled separately, will not work.

    For the large majority of use-cases, Coherence API can reconstruct programs correctly. If you are running into trouble, send us an email, and we'll get back to you as soon as possible.