Superface Map

Current Working Draft

Introduction

Superface map is a format describing one concrete implementation of a Superface profile. It essentially maps the application (business) semantics into provider’s interface implementation.

1Map Document

Defines a document that maps a profile into a particular provider’s API. At minimum, the map document consists of the profile and provider identifiers and a profile use‐case map.

Optionally, map document may specify a variant. Variant allows for mutliple maps for the same MapProfileIdentifier and ProviderIdentifier.

Example № 1profile = "conversation/send-message"
provider = "some-telco-api"

map SendMessage {
  ...
}

map RetrieveMessageStatus {
  ...
}
Example № 2profile = "conversation/send-message"
provider = "some-telco-api"
variant = "my-bugfix"

map SendMessage {
  ...
}

map RetrieveMessageStatus {
  ...
}

2Usecase Map

Map
mapUsecaseName{MapSlotlistopt}
Context Variables

Map context variables :

  • input - User input as stated in the profile
Example № 3map RetrieveMessageStatus {  
  http GET "/chat-api/v2/messages/{input.messageId}/history" {
    response 200 "application/json" {
      map result {
        deliveryStatus = body.history[0].state
      }
    }
  } 
}

2.1Map Result

MapResult
returnoptmap resultConditionoptSetMapResultVariablesopt
Example № 4map GetWeather {
  map result {
    airTemperature = 42  # Sets the value returned to user
  }
}

2.2Map Error

MapError
returnoptmap errorConditionoptSetMapErrorVariablesopt
Example № 5map GetWeather {
  map error {
    title = "Location not found"
  }
}

3Operation

Context Variables

Operation context variables :

Example № 6operation CountArray {
  return {
    answer = "This is the count " + args.array.length
  }
}

3.1Operation Return

Example № 7operation Foo {
  return if (args.condition) {
    message = "I have a condition!"
  }

  return {
    message = "Hello World!"
  }
}

3.2Operation Fail

Example № 8operation Foo {
  fail if (args.condition) {
    errorMessage = "I have failed!"
  }
}

4Set Variables

LHS
VariableNameVariableKeyPathObjectVariablelistopt
VariableKeyPathObjectVariable
KeyNameObjectVariable
Example № 9set {
  variable = 42
}
Example № 10set if (true) {
  variable = 42
}
Example № 11set {
  variable.key = 42
}
Example № 12set {
  variable = call ConvertToCelsius(tempF = 100)
}

5Operation Call

Condition and iteration

When both Condition and Iteration are specified, the condition is evaluated for every element of the iteration.

Context Variables

OperationCallSlot context variables:

  • outcome.data - data as returned by the callee
  • outcome.error - error as returned by the callee
Example № 13operation Bar {
  set {
    variable = 42
  }

  call FooWithArgs(text = `My string ${variable}` some = variable + 2 ) {
    return if (!outcome.error) {
      finalAnswer = "The final answer is " + outcome.data.answer
    }

    fail if (outcome.error) {
      finalAnswer = "There was an error " + outcome.error.message
    }
  }
}
Example № 14map RetrieveCustomers {
  // Local variables
  set {
    filterId = null
  }


  // Step 1
  call FindFilter(filterName = "my-superface-map-filter") if(input.since) {
    // conditional block for setting the variables
    set if (!outcome.error) {
      filterId = outcome.data.filterId
    }
  }

  // Step 2
  call CreateFilter(filterId = filterId) if(input.since && !filterId) {
    set if (!outcome.error) {
      filterId = outcome.data.filterId
    }
  }

  // Step 3
  call RetrieveOrganizations(filterId = filterId) {
    map result if (!outcome.error && outcome.data) {
      customers = outcome.data.customers
    }
  }

  // Step 4
  call Cleanup() if(filterId) {
    // ...
  }
}
Example № 15operation Baz {
  array = [1, 2, 3, 4]
  count = 0
  data = []

  call foreach(x of array) Foo(argument = x) if (x % 2) {
    count = count + 1
    data = data.concat(outcome.data)
  }
}
Note there is a convenient way to call operations in VariableStament. Using the OperationCallShorthand, the example above can be written as:
Example № 16operation Baz {
  array = [1, 2, 3, 4]
  data = call foreach(x of array) Foo(argument = x) if (x % 2)
  count = data.length
}

5.1Operation Call Shorthand

Used as RHS instead of JessieExpression to invoke an Operation in‐place. In the case of success the operation outcome’s data is unbundled and returned by the call. See OperationCall context variable outcome.

Example № 17set {
  someVariable = call Foo
}
Iteration and operation call shorthand

When an iteration is specified ther result of the OperationCallShorthand is always an array.

Example № 18operationOutcome = call SomeOperation()

users = call foreach(user of operationOutcome.users) Foo(user = user) if (operationOutcome)

// Intepretation: 
// `Foo` is called for every `user` of `operationOutcome.users` if the `operationOutcome` is truthy

superusers = call foreach(user of operationOutcome.users) Bar(user = user) if (user.super)

// Intepretation: 
// `Bar` is called for an `user` of `operationOutcome.users` if the `user.super` is truthy

6Outcome

Evaluation of a use‐case map or operation outcome. The outcome definition depends on its context. When specified in the Map context the outcome is defined as SetMapOutcome. When specified in the Operation context the outcome is defined as SetOperationOutcome.

6.1Map Outcome

Outcome in the Map context.

6.2Operation Outcome

Outcome in the Operation context.

7Network Operation

NetworkCall
GraphQLCall

8HTTP Call

HTTPMethod
GETHEADPOSTPUTDELETECONNECTOPTIONSTRACEPATCH
Example № 19map SendMessage {
  http POST "/chat-api/v2/messages" {
    request "application/json" {
      body {
        to = input.to
        channels = ['sms']
        sms.from = input.from
        sms.contentType = 'text'
        sms.text = input.text
      }
    }

    response 200 "application/json" {
      map result {
        messageId = body.messageId
      }
    }
  }
}

8.1HTTP Transaction

HTTPTransaction
HTTPSecurityoptHTTPRequestoptHTTPResponselistopt

8.2HTTP Security

8.2.1Api Key Security Scheme

ApiKeyPlacement
queryheader

Authentication using an arbitrary API key.

Example № 20GET "/users" {
  security apikey header {
    name = "my-api-key-header"
  }

  response {
    ...
  }
}
Context Variables

Using this scheme injects the following variables into the HTTPRequest‘s context:

  • security.apikey.key - API key

8.2.2Basic Security Scheme

Basic
basic

Basic authentication scheme as per RFC7617.

Context Variables

Using this scheme injects the following variables into the HTTPRequest‘s context:

  • security.basic.username - Basic authentication user name
  • security.basic.password - Basic authentication password
Example № 21GET "/users" {
  security basic
  
  response {
    ...
  }
}

8.2.3Bearer Security Scheme

Bearer
bearer

Bearer token authentication scheme as per RFC6750.

Context Variables

Using this scheme injects the following variables into the HTTPRequest‘s context:

  • security.bearer.token - Bearer token
Example № 22GET "/users" {
  security bearer
  
  response {
    ...
  }
}

8.2.4Oauth Security Scheme

Add support for Oauth2

8.2.5No Security Scheme

None
none

Default security scheme if no other HTTPSecurity is provided. Explicitly signifies public endpoints.

Example № 23GET "/public-endpoint" {
  security none
  
  response {
    ...
  }
}

8.3HTTP Request

Example № 24http GET "/greeting" {
  request {
    query {
      myName = "John"
    }
  }
}
Example № 25http POST "/users" {
  request "application/json" {
    query {
      parameter = "Hello World!"
    }

    headers {
      "my-header" = 42
    }

    body {
      key = 1
    }
  }
}
Example № 26http POST "/users" {
  request "application/json" {
    body = [1, 2, 3]
  }
}

8.4HTTP Response

HTTPRespose
responseStatusCodeoptContentTypeoptContentLanguageopt{HTTPResponseSlotlistopt}
Context Variables

HTTPResponseSlot context variables :

  • statusCode - HTTP response status code parsed as number
  • headers - HTTP response headers in the form of object
  • body - HTTP response body parsed as JSON
Example № 27http GET "/" {
  response 200 "application/json" {
    map result {
      outputKey = body.someKey
    }
  }
}
Example № 28http POST "/users" {
  response 201 "application/json" {
    return {
      id = body.userId
    }
  }
}

Handling HTTP errors:

Example № 29http POST "/users" {
  response 201 "application/json" {
    ...
  }
  
  response 400 "application/json" {
    error {
      title = "Wrong attributes"
      details = body.message
    }
  }
}

Handling business errors:

Example № 30http POST "/users" {
  response 201 "application/json" {
    map result if(body.ok) {
      ...
    }

    map error if(!body.ok) {
      ...
    }
  }
}

When ContentType is not relevant but ContentLanguage is needed, use the * wildchar in place of the ContentType as follows:

Example № 31http GET "/" {
  response  "*" "en-US" {
    map result {
      rawOutput = body
    }
  }
}

9Conditions

Conditional statement evalutess its JessieExpression for truthiness.

Example № 32if ( true )
Example № 33if ( 1 + 1 )
Example № 34if ( variable % 2 )
Example № 35if ( variable.length == 42 )

10Iterations

When the given JessieExpression evaluates to an array (or any other ECMA Script iterable), this statement iterates over its elements assigning the respective element value to its context VariableName variable.

Example № 36foreach (x of [1, 2, 3])
Example № 37foreach (element of variable.nestedArray)

11Jessie

Define what is Jessie and what expression we support
JessieExpression
JessieScript

12Language

12.1Source text

SourceCharacter
/[\u0009\u000A\u000D\u0020-\uFFFF]/

12.1.1Comments

Example № 38// This is a comment

12.1.2Line Terminators

LineTerminator
New Line (U+000A)
Carriage Return (U+000D)New Line (U+000A)
Carriage Return (U+000D)New Line (U+000A)

12.2Common Definitions

12.2.1Identifier

Identifier
/[_A-Za-z][_0-9A-Za-z]*/

12.2.2Profile Identifier

DocumentNameIdentifier
/[a-z][a-z0-9_-]*/

Identifier of a profile regardless its version.

Example № 39character-information
Example № 40starwars/character-information

12.2.3Full Profile Identifier

Fully disambiguated identifier of a profile including its exact version.

Example № 41character-information@2.0.0
Example № 42starwars/character-information@1.1.0

12.2.4Map Profile Identifier

Profile identifier used in maps does not include the patch number.

Example № 43starwars/character-information@1.1

12.2.5Provider Identifier

12.2.6URL Value

URLValue
"URL"

12.2.7String Value

12.2.8Integer Value

IntegerValue
/[0-9]+/

AAppendix: Keywords

§Index

  1. ApiKey
  2. ApiKeyPlacement
  3. Argument
  4. Basic
  5. Bearer
  6. Comment
  7. CommentChar
  8. Condition
  9. ContentLanguage
  10. ContentType
  11. DocumentNameIdentifier
  12. EscapedCharacter
  13. FullProfileIdentifier
  14. HTTPBody
  15. HTTPBodyValueDefinition
  16. HTTPCall
  17. HTTPHeaders
  18. HTTPMethod
  19. HTTPRequest
  20. HTTPRequestBodyAssignment
  21. HTTPRequestSlot
  22. HTTPResponseSlot
  23. HTTPRespose
  24. HTTPSecurity
  25. HTTPSecurityScheme
  26. HTTPStatusCode
  27. HTTPTransaction
  28. Identifier
  29. IntegerValue
  30. Iteration
  31. JessieExpression
  32. KeyName
  33. LHS
  34. LineTerminator
  35. MajorVersion
  36. Map
  37. MapDocument
  38. MapError
  39. MapProfileIdentifier
  40. MapResult
  41. MapSlot
  42. MinorVersion
  43. NetworkCall
  44. None
  45. Operation
  46. OperationArguments
  47. OperationCall
  48. OperationCallShorthand
  49. OperationCallSlot
  50. OperationFail
  51. OperationName
  52. OperationReturn
  53. OperationSlot
  54. PatchVersion
  55. Profile
  56. ProfileIdentifier
  57. ProfileName
  58. ProfileScope
  59. Provider
  60. ProviderIdentifier
  61. RHS
  62. SemanticVersion
  63. SetMapErrorVariables
  64. SetMapOutcome
  65. SetMapResultVariables
  66. SetOperationFailVariables
  67. SetOperationOutcome
  68. SetOperationReturnVariables
  69. SetOutcome
  70. SetVariables
  71. SourceCharacter
  72. StringCharacter
  73. StringValue
  74. URLPath
  75. URLPathLiteral
  76. URLPathSegment
  77. URLPathVariable
  78. URLQuery
  79. URLTemplate
  80. URLValue
  81. UsecaseName
  82. VariableKeyPath
  83. VariableName
  84. VariableStatement
  85. VariableStatements
  86. Variant
  1. 1Map Document
  2. 2Usecase Map
    1. 2.1Map Result
    2. 2.2Map Error
  3. 3Operation
    1. 3.1Operation Return
    2. 3.2Operation Fail
  4. 4Set Variables
  5. 5Operation Call
    1. 5.1Operation Call Shorthand
  6. 6Outcome
    1. 6.1Map Outcome
    2. 6.2Operation Outcome
  7. 7Network Operation
  8. 8HTTP Call
    1. 8.1HTTP Transaction
    2. 8.2HTTP Security
      1. 8.2.1Api Key Security Scheme
      2. 8.2.2Basic Security Scheme
      3. 8.2.3Bearer Security Scheme
      4. 8.2.4Oauth Security Scheme
      5. 8.2.5No Security Scheme
    3. 8.3HTTP Request
    4. 8.4HTTP Response
  9. 9Conditions
  10. 10Iterations
  11. 11Jessie
  12. 12Language
    1. 12.1Source text
      1. 12.1.1Comments
      2. 12.1.2Line Terminators
    2. 12.2Common Definitions
      1. 12.2.1Identifier
      2. 12.2.2Profile Identifier
      3. 12.2.3Full Profile Identifier
      4. 12.2.4Map Profile Identifier
      5. 12.2.5Provider Identifier
      6. 12.2.6URL Value
      7. 12.2.7String Value
      8. 12.2.8Integer Value
  13. AAppendix: Keywords
  14. §Index