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 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 (but you can build your app in any language/framework that you want):
@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). Its 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):
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.
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):
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.:
curl \
--request POST \
--header "Content-Type:application/json" \
--header "tazzy-secret: YOURAPPSSECRETKEY" \
--data '{ "hello": "world" }' \
"https://02b4aeca.ngrok.io/tas/core/tenants"
Again, 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.
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.
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.
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/organization 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:
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 storefont 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.
First, create the actual API endpoint in your code. See the Programming guide for details of producing 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):
@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):
curl \
--request POST \
--header "Content-Type:application/json" \
--header "tazzy-secret: YOURAPPSSECRETKEY" \
--data '{ "hello": "world" }' \
"http://localhost:8080/t/acme/tas/devs/tas/appStatus"
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.
Previously, we made your endpoint reachable on the internet, possibly with ngrok. You also updated your app's definition to enter this public address.
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.