Getting started

One of the first things to achieve when building an app is producing APIs - i.e. getting the endpoints in your server hit correctly by other apps and by TAS itself, e.g.:

to learn about new customers (i.e. tenants that have installed your app)
to control your app's launch page and setup icon

To get started, create an app, and install it into a new tenant.

At this point, you've only flipped a few bits on TAS's servers. Your app doesn't have any code - its purely virtual.

Let's now get some code working. A good place to start is to produce the core out API POST /tenants/{tenant}. The TAS core (i.e. TAS itself) calls this API on your app whenever a tenant installs it. Its a good point for you to, e.g. insert a row into your customer table, send an email to your sales team, etc.

First, create an actual API endpoint in your code. See the Programming guide for details of producing a core-out API.

In this case the API you want to produce is POST /tenants/{tenant}, so your endpoint should live at /tas/core/tenants. Here's an example in Java/Spring:

You can build your app in any language / framework that you want.

-- CODE language-java line-numbers --
@RequestMapping(value = "/tas/core/tenants", method = RequestMethod.POST)
public void createTenant (
@PathVariable String tenant,
  @RequestBody String body,
  @RequestHeader("tazzy-secret") String secret
) {
    logger.info("in POST /tenants for tenant " + tenant + " with payload " + body );
    if ( ! secret.equals(SECRET) ) throw
      new UnauthorizedException(); // check incoming tazzy-secret
}

Check that the incoming tazzy-secret key matches the secret key of your app (you can find your app's secret key on the developer site). It's critical that you always perform this check, for all incoming traffic. Failing to do so would allow an attacker to call your APIs directly, bypassing all TAS security.

Now spin up your code. In this case, we'll assume your app is running on port 8080.

If you want, you can now check locally that your endpoint is working using a command like curl (in other words, you're making the same call that TAS core will when your app is fully wired in):

-- CODE language-curl --
curl \
--request POST \
--header "Content-Type:application/json" \
--header "tazzy-secret: YOURAPPSSECRETKEY" \
--data '{ "hello": "world" }' \
"http://localhost:8080/tas/core/tenants"

You should see a log message from your own code telling you that your endpoint has been hit. Once you've achieved this, you're ready to move on.

When your app is live, your endpoint will receive a legitimate payload. In the example above, we just sent a dummy payload.

Publish your endpoint

Next, for anyone else to call your endpoint, it needs to be reachable on the internet (If you're working on an internet-connected server, then you can skip this step).

If you're working on your own laptop, then most likely your networking will not allow incoming traffic to reach it. In these examples, we'll use the popular tool ngrok as a way around this. ngrok creates a publicly visible tunnel that reaches in to your own machine. (Using ngrok is a pragmatic way to get up and running quickly, but its not great security or a long term solution - sooner or later you'll need to host your app on a proper, internet-connected server).

Download and start up ngrok like this:

./ngrok http 8080

ngrok should start up, and display something like the following, showing you the public addresses of your two tunnels (one each for http and https):

-- CODE language-console --
Forwarding http://02b4aeca.ngrok.io -> localhost:8080
Forwarding https://02b4aeca.ngrok.io -> localhost:8080

Once again, if you want, you can check the connectivity by calling your API with curl, but this time using the public, internet-facing address, e.g.:

You should see a log message telling you that your endpoint has been hit. Once you've achieved this, you're ready to move on.

Specify your server details on your app

Now that your app's server is up and running on the internet, you need to update your app's definition so that TAS knows where it is.

Open your app in the developer site, and click "Tazzy". Your server is the upstream, so enter its address (in this example, https://02b4aeca.ngrok.io) into the "Back end server" field, and save your changes.

Test it

You should have full connectivity now, so now return to your tenant, uninstall your app, and then install it again.

If your API is working OK, then you should see a log message each time a tenant installs your app.

Congratulations! You've produced a core-out API.

Now, let's produce a tenant API call, in this case to show your app's setup screen.

Producing the GET /appStatus API

A common requirement for a setup screen is that, when a user installs your app, you want to connect the tenant in TAS to a customer/tenant/organisation in your own system. A common way to do this is to ask the user to log in to your system, and then join the dots behind the scenes so that you know which of your customers the TAS tenant "aardvark" (for example) corresponds to.

The user experience will be:

The user clicks and installs your app.
The app renders your app with a red "setup required" button displayed.
The user clicks on the "setup required" button, and is led to a web page in your app. Embedded in the link is the TAS tenant.
The user logs in to your system, which then records the link between that user's organisation in your system and the TAS tenant that was passed across in the link.

To break this down, the first thing you need to do is to cause the setup icon to be displayed on top of your app in the storefront. As with most things TAS, this happens via an API call (to the GET /appStatus API in this case).

You might expect this to be a core API call, but since the storefront itself is an app, this is a tenant API call (i.e., the storefront app is the consumer and your app is the producer).

The storefront app regularly tries to call GET /appStatus on every installed app. To cause the setup icon to be displayed, you just need to produce this API, and return a response with details of your setup screen.

Create your endpoint

First, create the actual API endpoint in your code. See our guide for details of how to produce a tenant API.

So your endpoint should be:

/t/{tenant}/tas/devs/tas/appStatus

Here's an example in Java/Spring (but you can build your app in any language/framework that you want):

-- CODE language-java --
@RequestMapping(value = "/t/{tenant}/tas/devs/tas/appStatus", method = RequestMethod.GET)
  public void createTenant(
    @PathVariable String tenant,
    @RequestHeader("tazzy-secret") String secret) {
      if (! secret.equals(SECRET)) throw
        new UnauthorizedException(); // check incoming tazzy-secret

        .. now return a JSON object for the app status, e.g. setup required etc.
    }

Now spin up your code. In this case, we'll assume your app is running on port 8080.

If you want, you can now check locally that your endpoint is working using a command like curl (in other words, you're making the same call that TAS core will when your app is fully wired in):

You should see a log message from your own code telling you that your endpoint has been hit. Once you've achieved this, you're ready to move on.

Publish your endpoint

Previously, we made your endpoint reachable on the internet, possibly with ngrok. You also updated your app's definition to enter this public address.

Test it

You should have full connectivity now, so now return to your tenant, open the storefront, and open your app. You should now see the effect of the data you passed back to this API call. For example, if you provided a url, then the "Open" button should appear on your app, linked to the url you specified.