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
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) {
// ...
}
}
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
8HTTP Call
GET | HEAD | POST | PUT | DELETE | CONNECT | OPTIONS | TRACE | PATCH |
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
8.2HTTP Security
8.2.1Api Key Security Scheme
query | header |
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 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 № 18GET "/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 № 19GET "/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 № 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
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
11Language
11.1Source text
11.1.1Comments
Example № 29// This is a comment
11.1.2Line Terminators
11.2Common Definitions
11.2.1Identifier
11.2.2Profile Identifier
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
11.2.7String Value
" | \ | / | n | r | t |
11.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
- 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