The essence of an API | smart mocks

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 a 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 about this new functionality. We will merge text with a simple business-oriented DSL capturing the requirements:

When creating an 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)

Continuous testing | forever

When this API is implemented somewhere, we just need to add a redirect, besides the mock:

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, will continue to work... and, 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!