Tutorial¶

A Simple Open Service¶

We will assume that you have followed the instructions in the reference to email Authentise and get a Group URI. For this tutorial we will assume your group URI is https://users.authentise.com/group/abc-123/.

Let’s begin by getting your service registered. We will assume that you have a model-healing service called healmymodels.com. The instructions are very similar for other services. My model healing service can take requests for healing at https://healmymodels.com/integrations/3DIAX/. I can now register my service with:

POST https://integrations.authentise.com/service/
Content-Type application/json
{
    "name"              : "Tutorial Model Healer",
    "description"       : "A model healing service to be used during this tutorial",
    "type"              : "model-healing",
    "group_uri"         : "https://users.authentise.com/group/abc-123/",
    "service_url"       : "https://healmymodels.com/integrations/3DIAX/",
}
Location: https://integrations.authentise.com/service/111-222/

This request includes our 3 essential pieces of information: the type which identifies that we have a model healing service, the group_uri that we were given from Authentise, and the service_url where users’ requests will be sent for your service to handle. The name and description can be anything you want, though the name must be unique in the system and it will be displayed to users in the registry.

The response to this request will contain a Location header which identifies where you can make updates to this resource if you would like to change the name or the service_url

Alright, now your service is registered! That was easy. We can take a look at your entry by asking the register for similar services:

GET https://integrations.authentise.com/service/?filter[type]=model-healing
Content-Type: application/json
{
    "resources" : [...{
        "name"              : "Tutorial Model Healer",
        "description"       : "A model healing service to be used during this tutorial",
        "type"              : "model-healing",
        "group_uri"         : "https://users.authentise.com/group/abc-123/",
        "service_url"       : "https://healmymodels.com/integrations/3DIAX/",
        "uri"               : "https://integrations.authentise.com/service/111-222/"
    }, ...]
}

The response will of course contain many entries (all of them under ‘resources’). I have removed the other matches here. But there is your service! Users of the system will see the service as well and be able to start using it right away. So what does it look like when a user uses the service? Well, let’s go over a simple case - your service is free and useable by anyone. A user would come to 3DIAX and make a request like this:

POST https://integrations.authentise.com/operation/
Content-Type: application/json
{
    "service"   : "https://integrations.authentise.com/service/111-222/",
    "inputs"    : {
        "model" : "https://models.authentise.com/model/aaa-bbb/",
    },
    "parameters": {
        "something" : "a-value"
    }
}
Location: https://integrations.authentise.com/operation/333-333/

This request specifies the URI of your service, https://integrations.authentise.com/service/111-222/, and a model to be healed. The model is a URI contained in 3DIAX. The final parameter, parameters I’ve filled with a placeholder value, something. These parameters will be passed through to your service. Your service needs to be sure to validate them and send back appropriate responses with error codes. 3DIAX will not validate nor interpret anything provided by the user in parameters. This allows your service to have arbitrary parameters that the user can control through 3DIAX.

When 3DIAX receives this request it will look up your service by its URI and see that your service for model-healing expects to receive a request at https://healmymodels.com/integrations/3DIAX/. It will then make a request like this:

POST https://healmymodels.com/integrations/3DIAX/
Content-Type: application/json
{
    "input"         : {
        "model"     : "https://models.authentise.com/model/aaa-bbb/"
    },
    "parameters"    : {
        "something" : "a-value"
    }
    "callback"      : {
        "method"    : "PUT",
        "url"       : "https://integrations.authentise.com/operation/333-333/"
    },
    "user"          : "https://users.authentise.com/user/4444-5555/"
}

This indicates that healmymodels.com should heal the model at https://models.authentise.com/model/aaa-bbb/. Most of these values are pass-through. The input is the same provided by the user when they created the operation. The parameters are the same. The user value identifies the user that initiated the request in 3DIAX. The callback parameter means that healmymodels.com should process the job and send callback information on the job to https://integrations.authentise.com/operation/333-333/ via PUT. The URL https://models.authentise.com/model/aaa-bbb/ identifies a resource. healmymodels.com will need to download the resource and then download its content:

GET https://models.authentise.com/model/aaa-bbb/
Content-Type: application/json
{
    ...
    "content" : "https://secure.authentise.com/xxx/"
}

The content property will contain a URL that returns a binary stream of data that is the content of the model. healmymodels.com should download this data and perform its healing operation on it.

Callbacks¶

As the operation progresses it should make periodic callbacks to 3DIAX to notify it (and its user) of progress. A request to update status looks like this:

PUT https://integrations.authentise.com/operation/333-333/
Content-Type: application/json
{
    "status"    : "some-status",
}

This update indicates that the operation is in state some-status. The status can be anything and have any meaning. Every time the status changes 3DIAX will notify the original user via whatever notification settings they have expressed. As a rule of thumb it is a good idea to notify the user when the job has begun processing, when any errors have been encountered, and periodically during the process if the process takes longer than a few minutes. There is really only one callback that is required - telling 3DIAX the operation is complete. That request would look like this:

PUT https://integrations.authentise.com/operation/333-333/
Content-Type: application/json
{
    "status"    : "complete",
    "result"    : "https://healmymodels.com/securestorage/1232456/"
}

This will cause 3DIAX to download the model located at https://healmymodels.com/securestorage/123456/ and use that data as the content of the healed model. 3DIAX will also inform the user that the operation is complete and that they can retrieve their updated data.

If the operation had encountered some kind of error during processing the user could be notified with

PUT https://integrations.authentise.com/operation/333-333/
Content-Type: application/json
{
    "status"    : "error",
    "error"     : {
        "code"  : "model-is-made-of-cats",
        "title" : "Your model was found to be made entirely of cats. Processing cannot continue."
    }
}

This error would be noted on the /operation/ resource and reported to the user. The code should contain a unique identifier in your system for the error. The title should contain a human-readable description in English of the cause of the error. Keep in mind both values will be displayed to the user.

These are the only two callback status values that have particular meaning and require a particular payload: complete and error. Additional values in the payload will be ignored. Arbitrary status values will be reported to the user that originally requested the operation. That’s it!

If that model works for your service (free to use, open), you can stop here. But, if your service requires that users pay or be identified in some way, read on.

Fill in information on JWT and user binding below after its built