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

Security requirement referencing an API security scheme defined in provider definition.

Example № 20GET "/users" {
  security apikey api_key_scheme_id

  response {
    ...
  }
}

8.2.2Basic Security Scheme

Security requirement eferencing a basic authentication scheme defined in provider definition as per RFC7617.

Example № 21GET "/users" {
  security basic basic_scheme_id
  
  response {
    ...
  }
}

8.2.3Bearer Security Requirement

Security requirement referencing a bearer token authentication scheme defined in provider definition as per RFC6750.

Example № 22GET "/users" {
  security bearer bearer_scheme_id
  
  response {
    ...
  }
}

8.2.4Oauth Security Requirement

Add support for Oauth2

8.2.5No Security Requirement

None
none

Default security requirement 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.7Security Scheme Identifier

References the security scheme found within a provider definition.

12.2.8String Value

12.2.9Integer Value

IntegerValue
/[0-9]+/

AAppendix: Keywords

§Index

  1. ApiKey
  2. Argument
  3. Basic
  4. Bearer
  5. Comment
  6. CommentChar
  7. Condition
  8. ContentLanguage
  9. ContentType
  10. DocumentNameIdentifier
  11. EscapedCharacter
  12. FullProfileIdentifier
  13. HTTPBody
  14. HTTPBodyValueDefinition
  15. HTTPCall
  16. HTTPHeaders
  17. HTTPMethod
  18. HTTPRequest
  19. HTTPRequestBodyAssignment
  20. HTTPRequestSlot
  21. HTTPResponseSlot
  22. HTTPRespose
  23. HTTPSecurity
  24. HTTPSecurityRequirement
  25. HTTPStatusCode
  26. HTTPTransaction
  27. Identifier
  28. IntegerValue
  29. Iteration
  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. SecuritySchemeIdentifier
  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 Requirement
      4. 8.2.4Oauth Security Requirement
      5. 8.2.5No Security Requirement
    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.7Security Scheme Identifier
      8. 12.2.8String Value
      9. 12.2.9Integer Value
  13. AAppendix: Keywords
  14. §Index