Map use case to a provider
Map is a Comlink document that defines how a specific use case is fulfilled by a provider. It creates a mapping between the abstract use case and the concrete HTTP requests necessary to integrate with the provider.
Setup
This guide assumes you have a project set up with Superface installed. If you need to set up a new project, please reference the Setup Guide.
Prerequisites
- Existing profile with use case definition
- Existing provider definition
Create new Map document
Mapping happens between a specific version of Profile and some Provider. Choose which profile version you want to fulfill by the provider.
The easiest way to then bootstrap a new Map document is using Superface CLI.
superface create:map <profile-name> <provider-name>
Replace the <profile-name> and <provider-name> in the command with the actual profile and provider you wish to create new Map for.
Running the above command creates a new Comlink file and links the new map in your local super.json configuration file. The new map will look something like this:
profile = "<profile-name>@<version>"
provider = "<provider-name>"
// Complete map specification: https://superface.ai/docs/comlink/reference/map
map UsecaseName { // UseCaseName will be different based on the actual use case in the profile
// Available input fields:
// `input.field` - required string
// -----------------------
// 1) Change HTTP method and path to make an HTTP call
// provider base URL https://swapi.dev/api - base url will be different based on the actual url in provider.json
http POST "/endpoint/api/{ input.field }" {
// 2) Specify security scheme id from Provider JSON definition
security none
// 3) Pass input values to the HTTP request
request {
query {
// param_name = input.fieldName
}
headers {}
body {}
}
// 4) Map successful HTTP response to the result. The content type is optional
response 200 "application/json" {
return map result {
outputField = "", // optional nulllable string
}
}
// 5) Optionally map unsuccessful HTTP response to the use case error
response 500 {
return map error {
title = "", // required string
detail = "", // optional string
}
}
}
}
Map use cases
Every profile defines one or more use cases. You need to map the use cases to concrete requests to be made to the provider API, and specify how to handle the responses. If you used the CLI to bootstrap the map, it will have pre-defined stub mappings for every profile use case.
Reading use case inputs
Use cases usually define & expect some inputs from the user. These inputs are defined in profile in the dedicated field.
You can access these inputs via the input object which is available inside a map. If you used the CLI to bootstrap the map, the resulting map lists all inputs (eq. // input.field - required string) defined by the use case. Each input is paired with its description, containing information about its type, if it is required, and if it can be null.
Example
Given the following use case definition in a profile:
...
usecase GetWeather {
input {
location
units
}
result {
...
}
}
...
These input props are accessible in the use case mapping.
...
map GetWeather {
// `input` object available
// `input.location`
// `input.units`
}
...
Make HTTP request
The resulting map contains numbered comments guiding you through mapping of the use case. Start with specifying the HTTP method, and the URL. The provider's default service base URL is provided in the surrounding comments for your convenience. See Comlink reference for specifying a different service.
All widely known HTTP methods are supported. The path is a simple string, but can be templated. E.g. if you need to request resource whose ID was provided in the input, you might want to use something like /endpoint/api/{ input.field }.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
}
}
The above definition makes a POST HTTP call to the provider's default service on path /api/messages.
Authenticate the request (optional)
To authenticate the request, simply reference the security scheme ID you want to use for the specific request. Security schemes are defined in Provider JSON documents, and the created map already lists the available security schemes. If the provider does not require any type of authentication, you can use security none.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
}
}
Replace scheme-id with one of the schemes defined for the provider you're mapping to.
See Comlink reference for details on security definition.
Pass data to request
You can pass any data to the request by adding a request block. Inside, you can pass data to headers, query or body by specifying headers, query or body blocks, respectively. The map created by CLI already contains these blocks, so you just need to pass the data, likely using the input object.
When passing data in body, it's a best practice to also define the request content type.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
request "application/json" {
query {
from = input.from
}
body {
to = input.to
text = input.text
}
}
}
}
The above definition makes call to /api/messages?from=... with body of content type application/json including object with 2 parameters (to & text).
See Comlink reference for details on request block.
Handle server responses
You can handle various server responses by introducing one or more response blocks inside http block. Responses are matched with their respective handler by a combination of status code, content type and content language.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
request "application/json" { /* ... */ }
response 201 "application/json" {
// handler context for success response
}
response 400 "application/problem+json" {
// handler context for error response
}
}
}
The above example definition:
- handles any response with status code
201andapplication/jsoncontent type in success context, - handles any response with status code
400andapplication/problem+jsoncontent type in error context.
Any other response won't be handled and will result in an unexpected error.
See Comlink reference for details on response block & response matching.
Some APIs always return a single status code (usually 200) and mark the response successful/failed somehow in body (either via a boolean flag or by the response format). For such APIs, use a single response handler and refer to Conditional mapping below.
Access response data
Every response block creates a context that automatically exposes the response data via 3 variables:
statusCode(number): HTTP response status codeheaders(object): HTTP response headersbody(object): HTTP response body
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
request "application/json" { /* ... */ }
response 201 "application/json" {
// code in this block can reference `statusCode`, `headers` & `body`
}
}
}
See Comlink reference for details on context variables inside response block.
Map use case result
Typically, use cases expect some result to be returned after they are performed. For some, it may be a simple confirmation of the success (e.g. SMS was sent, here's in ID). For others, the result may be the sole reason you care about the use case (e.g. Found this address for given coordinates).
Map the use case result from the provider's HTTP response using map result statement. Note that you must resolve to the same result interface as defined in the profile document.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
request "application/json" { /* ... */ }
response 201 "application/json" {
map result {
messageId = body.message_sid
remainingMessages = headers["X-CREDIT-LEFT"] / 0.3
}
}
}
}
The above definition maps the 2 expected result fields. One from the response's body, the other is loaded from headers and transformed with a simple Comlink expression.
See Comlink reference for detailed specification of map result statement.
map result is a regular Comlink statement; and as such can theoretically happen from anywhere inside the use case mapping, not necessarily from an inside of the response handler. An example of this would be a use case that doesn't need to call a remote server. However this is very rare and the results are usually mapped from the HTTP responses so the example shows the most common place where the result mapping happens.
Map errors
In addition to the result, use cases sometimes also expect a specific error interface to be returned from the perform if it fails.
This is very useful as you can map the provider specific API errors (that usually use a technical language) to nicer and more helpful errors that use the language of the use case domain. If the profile defines error expectation, you should strongly consider mapping the possible errors since this dramatically improves the usability of the use case.
Map all the possible use case errors from the provider's HTTP responses using map error statement. Note that you must resolve to the same error interface as defined in the profile document.
It's very common for maps to include various different error mappings, each for a different error scenario.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
request "application/json" { /* ... */ }
response 201 "application/json" { /* ... */ }
response 429 {
map error {
title = "Sending messages too frequently"
details = (`You can send more message after ${headers['Retry-After']} seconds`)
}
}
}
}
The above definition maps the 2 expected error fields when server responds with status 429 (Too Many Requests). One is hardcoded as it describes the error scenario, the other constructs a helpful message with a value from response headers using a simple Comlink expression.
See Comlink reference for detailed specification of map error statement.
map error is a regular Comlink statement; and as such can theoretically happen from anywhere inside the use case mapping, not necessarily from an inside of the response handler. Although the errors are usually mapped from the failed HTTP responses, sometimes you might want to map error from different places. One example would be validating the inputs against some domain rule. In such case, you might want to map error (or; fail early) when invalid inputs were provided, even before making the request.
Conditional mapping
Always 200
Some APIs don't follow the HTTP conventions and choose to return the same status code on every response (typically the success 200), then differentiate between a success and fail using a flag in the body or a similar mechanism.
When dealing which such APIs, map the result & errors based on a condition rather than from an inside of different response handlers.
profile = "<profile-name>@<version>"
provider = "<provider-name>"
map UseCaseName {
http POST "/api/messages" {
security "scheme-id"
request "application/json" { /* ... */ }
response 200 "application/json" {
map error if (body.error) {
title = "Couldn't send the message"
detail = body.error.reason
}
map result {
messageId = body.data.message_sid
remainingMessages = body.data.credits_left / 0.3
}
}
}
}
The above definition maps the use case outcome based on the presense and value of error body param. If error param is present and truthy, the outcome of the use case in “error” (incl. some details). Otherwise, the use case's outcome is a valid “result” that maps data from data body object.
Example: Server responses mapped in above definition
{
"error": null,
"data": {
"message_sid": "76TUA987ZHAX",
"credits_left": 5.1
}
}
{
"error": {
"reason": "You ran out of credits. Please top up your account."
},
"data": null
}
See Comlink reference for more about conditions.
Multiple errors
Mapping based on a condition is useful for handling multiple error cases coming under a single response status. This is common for 400 (Bad Request) errors.
response 400 "application/problem+json" {
return map error if (body.error_code === "InvalidPhone") {
title = "Invalid phone number"
detail = "Please provide phone number in E.164 format"
}
return map error if (body.error_code === "InvalidKey") {
title = "Unauthorized"
detail = "Please provide a valid API key in format 'TWL_8765678X'"
}
map error {
title = "Unexpected Error"
}
}
The above map expects the use case to fail in some scenarios when the user provides invalid inputs. It handles these scenarios by matching error_code returned in the response body and maps these technical enum values to much more helpful title & detail readable to the end user. Then, a regular map error without a condition is used to handle all other scenarios (which are clearly not expected to happen).
Note: the return keyword serves the purpose of early return, as you might recognize from other programming languages. Without return, the execution would continue to the map error without any condition at the end, and that would overwrite the error returned from the response handler.
See Comlink specification for more about conditions.
Using functions, conditions, iterations and more
The example Map snippets throughout this guide demonstrated only a portion of Comlink language.
For more complicated maps, you'll find a need for the general programming concepts like reusable functions, conditions, iterations, complex expressions or data manipulation.
Comlink supports everything you might expect from a powerful scripting language. We recommend to explore the language by consulting Comlink Map reference or the examples below.