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
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
Example № 4map GetWeather {
map result {
airTemperature = 42 # Sets the value returned to user
}
}
2.2Map Error
Example № 5map GetWeather {
map error {
title = "Location not found"
}
}
3Operation
Context Variables
Operation context variables :
- args - arguments as passed in the parent’s OperationCall
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
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 calleeoutcome.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)
}
}
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
8HTTP Call
GET | HEAD | POST | PUT | DELETE | CONNECT | OPTIONS | TRACE | PATCH |
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
8.2HTTP Security
8.2.1Api Key Security Scheme
query | header |
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 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 namesecurity.basic.password
- Basic authentication password
Example № 21GET "/users" {
security basic
response {
...
}
}
8.2.3Bearer Security Scheme
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
8.2.5No Security Scheme
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
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
12Language
12.1Source text
12.1.1Comments
Example № 38// This is a comment
12.1.2Line Terminators
12.2Common Definitions
12.2.1Identifier
12.2.2Profile Identifier
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
12.2.7String Value
" | \ | / | n | r | t |
12.2.8Integer Value
AAppendix: Keywords
§Index
- ApiKey
- ApiKeyPlacement
- Argument
- Basic
- Bearer
- Comment
- CommentChar
- Condition
- ContentLanguage
- ContentType
- DocumentNameIdentifier
- EscapedCharacter
- FullProfileIdentifier
- HTTPBody
- HTTPBodyValueDefinition
- HTTPCall
- HTTPHeaders
- HTTPMethod
- HTTPRequest
- HTTPRequestBodyAssignment
- HTTPRequestSlot
- HTTPResponseSlot
- HTTPRespose
- HTTPSecurity
- HTTPSecurityScheme
- HTTPStatusCode
- HTTPTransaction
- Identifier
- IntegerValue
- Iteration
- JessieExpression
- KeyName
- LHS
- LineTerminator
- MajorVersion
- Map
- MapDocument
- MapError
- MapProfileIdentifier
- MapResult
- MapSlot
- MinorVersion
- NetworkCall
- None
- Operation
- OperationArguments
- OperationCall
- OperationCallShorthand
- OperationCallSlot
- OperationFail
- OperationName
- OperationReturn
- OperationSlot
- PatchVersion
- Profile
- ProfileIdentifier
- ProfileName
- ProfileScope
- Provider
- ProviderIdentifier
- RHS
- SemanticVersion
- SetMapErrorVariables
- SetMapOutcome
- SetMapResultVariables
- SetOperationFailVariables
- SetOperationOutcome
- SetOperationReturnVariables
- SetOutcome
- SetVariables
- SourceCharacter
- StringCharacter
- StringValue
- URLPath
- URLPathLiteral
- URLPathSegment
- URLPathVariable
- URLQuery
- URLTemplate
- URLValue
- UsecaseName
- VariableKeyPath
- VariableName
- VariableStatement
- VariableStatements
- Variant