How to Get Started Building Serverless Backends with Dark
One of the earlier promises of serverless was a speedier time to resolution because you could start working without the need to set up infrastructure. I heard about Dark a year ago in a changelog podcast, and immediately looked at it. When it was unveiled in 2019, Dark was described as “a holistic programming language, editor, and infrastructure for building backends.” Although it sounds a bit mysterious, it was clearly set up to talk REST and, in their words, “Dark is a new way of building serverless backends.”
Dark is a little like one of those salsa lessons, where you feel the teachers are so good they can no longer remember what having no rhythm feels like. But working with HTTP and JSON is not unlike a formal dance. You send a request, and you receive a response. The body of the response is in JSON. There are conventions you should know, and some you can pick up. I assume for this article you are at least familiar with the music.
What the Dark interface does is automate some of the tedious communication. Above all this, you don’t have to write any code. We were to some degree sold a future in which coding would no longer be necessary, and that development would be democratized by voice recognition and well-developed user interfaces. That future is still a little further away, but it is wise to spot the patterns that are coming.
OK, now let’s dive straight into the Dark. You can immediately create a canvas by simply claiming a URL based on your username right in your browser, and then work on that page. Below I created “eastmad-thenewstack” and wrote a GET response for a “/greeting” endpoint.
Immediately, this will respond from the “builtwithdark” domain:
That was nice and fast. But I could have done this the other way around, and hit my endpoint with a novel request first, with no backend implementation:
Back on my canvas, Dark has stored the trace as a 404, so I can quickly work with it:
By hitting that plus, I will be able to respond to the GET request from “/leaving” in the same way I responded to “/greeting” above. This is what they refer to as Trace Driven Development. Working almost by reverse engineering traces does make you feel like a bit of a detective — almost, dare I say it, like a hacker. Except we are spying on a dance.
Revisiting the Dark site, they now have support for OAuth2, the three-way authorization trust tango between a Resource Owner, a client application and a Resource Server expressed in the language of tokens. Dark also has an example of creating a backend for a Slack App, which will be visible as a Slackbot. While the example is tricky, it does give us a chance to play with a set of useful techniques, including OAuth.
Even if you have admin authority for a Slack workspace, platform security is still carefully managed. A quick perusal of api.slack.com/app will show you a nice “Create an App” option, and looking at Basic Information you can see there is quite a lot of stuff:
(Note that full stop sitting in the middle of the numbers in that Client ID; this indicates it must be dealt with as a string.)
Now, we have to get a bit more into the intricacies of the dance. We need to create a Redirect URL within Slack that will start our trace procedure (look in ‘OAuth & permissions’).
Dark wants a user to use “/oauth-redirect” as the route to the canvas. Within Slack, go to Manage Distribution and copy the Shareable URL. Finally, we have something to call our backend with. By calling this we will hit our Dark canvas and start the trace.
Indeed, it is waiting in our canvas 404 list. We can now create the response to the GET:
So far, so good. We have triggered the redirect and we can see the full request that Dark got. So what do we send back? Well, we have our “Client Id” and “Client Secret” above from Slack. So we can create a POST within Dark and continue the dance.
We need to create a POST body, and this is where you need to think in JSON format — even though Dark kind of elides this. As we select the post response, Dark informs us of the parameters like any good IDE. A string for the URL to the Slack API, the body of the post, then two sets of key/value pairs that are themselves dictionaries.
The actual format of the body is mentioned in the example. The client_id and client_secret would be your strings of course:
So we are communicating directly with Slack’s OAuth API. Note that the value for the “code” key is taken from the request that Dark received (off the bottom of my image above), and it parses the JSON, so you can enter “request.queryParams.code”. When we send the POST, what we hope to get back are the correct access tokens.
I will stop the trace work here for this article, but if you want to continue with the example, follow the link above for the backend walkthrough to create a simple Slackbot. I admit I could not repeatedly get this to work — but with feedback, even failure is fairly instructive.
Conclusion
What have we picked up from all this?
- A smart user interface can work well for with familiar patterns, which users of IDEs and statically typed languages have been exploiting for years.
- REST continues to be a great way to form and understand APIs. The more complex payloads should just encourage more tools like Dark, that help explore service offerings.
- Working within various separate trust bodies or their simulations is a great way to understand a system, but it is still complicated. It is like holding several bunches of jangling keys and security cards, which must nevertheless be used in a specific order.
- Don’t stop the dance.
