Superface Map

Version 2021.02.19

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
.KeyName
KeyNameObjectVariable
Identifier
Example № 9set {
  variable = 42
}

Example № 10set if (true) {
  variable = 42
}

Example № 11set {
  variable.key = 42
}

Example № 12set {
  variable = call ConvertToCelsius(tempF = 100)
}

5Operation Call

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) {
    // ...
  }
}

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 № 15set {
  someVariable = call Foo
}

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
HTTPCall
GraphQLCall

8HTTP Call

HTTPMethod
GETHEADPOSTPUTDELETECONNECTOPTIONSTRACEPATCH
Example № 16map 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 № 17GET "/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 № 18GET "/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 № 19GET "/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 № 20GET "/public-endpoint" {
  security none
  
  response {
    ...
  }
}

8.3HTTP Request

Example № 21http GET "/greeting" {
  request {
    query {
      myName = "John"
    }
  }
}

Example № 22http POST "/users" {
  request "application/json" {
    query {
      parameter = "Hello World!"
    }

    headers {
      "my-header" = 42
    }

    body {
      key = 1
    }
  }
}

Example № 23http 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 № 24http GET "/" {
  response 200 "application/json" {
    map result {
      outputKey = body.someKey
    }
  }
}

Example № 25http POST "/users" {
  response 201 "application/json" {
    return {
      id = body.userId
    }
  }
}

Handling HTTP errors:

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

Handling business errors:

Example № 27http 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 № 28http GET "/" {
  response  "*" "en-US" {
    map result {
      rawOutput = body
    }
  }
}

9Conditions

10Jessie

Well define what is Jessie and what expression we support
JessieExpression
JessieScript

11Language

11.1Source text

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

11.1.1Comments

Example № 29// This is a comment

11.1.2Line Terminators

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

11.2Common Definitions

11.2.1Identifier

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

11.2.2Profile Identifier

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

Identifier of a profile regardless its version.

Example № 30character-information

Example № 31starwars/character-information

11.2.3Full Profile Identifier

Fully disambiguated identifier of a profile including its exact version.

Example № 32character-information@2.0.0

Example № 33starwars/character-information@1.1.0

11.2.4Map Profile Identifier

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

Example № 34starwars/character-information@1.1

11.2.5Provider Identifier

11.2.6URL Value

URLValue
"URL"

11.2.7String Value

11.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. JessieExpression
  31. KeyName
  32. LHS
  33. LineTerminator
  34. MajorVersion
  35. Map
  36. MapDocument
  37. MapError
  38. MapProfileIdentifier
  39. MapResult
  40. MapSlot
  41. MinorVersion
  42. NetworkCall
  43. None
  44. Operation
  45. OperationArguments
  46. OperationCall
  47. OperationCallShorthand
  48. OperationCallSlot
  49. OperationFail
  50. OperationName
  51. OperationReturn
  52. OperationSlot
  53. PatchVersion
  54. Profile
  55. ProfileIdentifier
  56. ProfileName
  57. ProfileScope
  58. Provider
  59. ProviderIdentifier
  60. RHS
  61. SemanticVersion
  62. SetMapErrorVariables
  63. SetMapOutcome
  64. SetMapResultVariables
  65. SetOperationFailVariables
  66. SetOperationOutcome
  67. SetOperationReturnVariables
  68. SetOutcome
  69. SetVariables
  70. SourceCharacter
  71. StringCharacter
  72. StringValue
  73. URLPath
  74. URLPathLiteral
  75. URLPathSegment
  76. URLPathVariable
  77. URLQuery
  78. URLTemplate
  79. URLValue
  80. UsecaseName
  81. VariableKeyPath
  82. VariableName
  83. VariableStatement
  84. VariableStatements
  85. Variant
Superface Map
  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. 10Jessie
  11. 11Language
    1. 11.1Source text
      1. 11.1.1Comments
      2. 11.1.2Line Terminators
    2. 11.2Common Definitions
      1. 11.2.1Identifier
      2. 11.2.2Profile Identifier
      3. 11.2.3Full Profile Identifier
      4. 11.2.4Map Profile Identifier
      5. 11.2.5Provider Identifier
      6. 11.2.6URL Value
      7. 11.2.7String Value
      8. 11.2.8Integer Value
  12. AAppendix: Keywords
  13. §Index