Smart mocks | the essence of an API

The first step in prototyping an API is to decouple the API's form from the function and prototype the conceptual API. Here's a simple service mock, which can simulate and mock the functionality, by example:

We have a mail server, which can create users:

$msg mailServer.create (user ?= "John") : (payload)

We can mock a few examples of this service:

$mock mailServer.create (user == "John@") 
=> (payload = {
  status:"Failed",
  error:"Illegal user name"
  })

$mock mailServer.create (user == "John") 
=> (payload = {
  status:"Success"
  })

$mock mailServer.create (user == "") 
=> (payload = {
  status:"Failed",
  error:"Illegal user name"
  })

dsl here...

result...

Note that ?= means could be like. It's very useful in providing examples and test values...

This is simply saying we have a message (or API) called mailServer.create. We can add descriptions and other documentation right alongside it. Also, we can mock it right here, to demonstrate how the API works, by example.

This service provides certain value to someone - how do we record this value and communicate it and test it?

Requirements and testing | stories

Next, we need to capture some requirements for this new functionality. We will merge text with a simple business-oriented DSL capturing the requirements:

When creating a user, we should get a status "Success":

$send mailServer.create (user="John")
$expect (payload.status is "Success")

If the user's name contains special characters we should get a failure:

$send mailServer.create (user = "John@")
$expect (payload.status is "Failed")

dsl here...

result...

We call this a story and it is basically a page in a wiki, which enables team development of use cases. It not only documents the requirements but also the acceptance criteria, which become automated tests. (You can run this test and trace it right now)

Smart API Connect | snakking

When this API is implemented somewhere, we just need to wire it in and connect it:

The actual server has this API:

$when mailServer.create (user)
=> snakk.json (url = "/diesel/rest/myActualServer/create/" + user, verb="POST")

dsl here...

result...

This will now go to the actual server and create the user, instead of just mocking it. However, the test stories we've defined, as well as any clients that send the message, will continue to work...

Continuous testing | forever

After connecting the API to the real server, if the actual server starts returning a different status, you will catch it right away... click "Run" on the test below:

If the user name contains special characters, create should fail:

$send mailServer.create (user = "John@")
$expect (payload.status is "Failed")

dsl here...

result...

These tests run continuously and make it very easy to catch when the actual service implementation diverges from the original requirements...

Innovate | ideas

This part is up to you, coming up with that great idea... we can help you with everything needed to prototype, test and develop it!