ballerina.net.http package

public struct Connection

Represents the HTTP server connector connection

Field Name Data Type Description Default Value
remoteHost string The server host name
port int The server port
  • < Connection > createSessionIfAbsent ( ) ( Session )

    Gets the Session struct for a valid session cookie from the connection. Otherwise creates a new Session struct.

    Return Variable Data Type Description
    Session
  • < Connection > forward ( InResponse res ) ( HttpConnectorError )

    Forwards inbound response to the caller

    Parameter Name Data Type Description
    res InResponse The inbound response message

    Return Variable Data Type Description
    HttpConnectorError
  • < Connection > getSession ( ) ( Session )

    Gets the Session struct from the connection if it is present

    Return Variable Data Type Description
    Session
  • < Connection > respond ( OutResponse res ) ( HttpConnectorError )

    Sends outbound response to the caller

    Parameter Name Data Type Description
    res OutResponse The outbound response message

    Return Variable Data Type Description
    HttpConnectorError
  • < Connection > respondContinue ( ) ( HttpConnectorError )

    Sends a 100-continue response to the client.

    Return Variable Data Type Description
    HttpConnectorError

public struct FollowRedirects

FollowRedirects struct represents HTTP redirect related options to be used for HTTP client invocation

Field Name Data Type Description Default Value
enabled boolean Enable redirect false
maxCount int Maximun number of redirects to follow 5

public struct HttpConnectorError

HttpConnectorError struct represents an error occured during the HTTP client invocation

Field Name Data Type Description Default Value
msg string An error message explaining about the error
cause error The error that caused HttpConnectorError to get thrown
stackTrace StackFrame[] Represents the invocation stack when HttpConnectorError is thrown
statusCode int HTTP status code

public struct InRequest

Represents an HTTP inbound request message

Field Name Data Type Description Default Value
rawPath string path: Resource path of request URI
method string HTTP request method
httpVersion string The version of HTTP
userAgent string User-Agent request header
extraPathInfo string path: Resource path of request URI
  • < InRequest > expects100Continue ( ) ( boolean )

    Checks whether the client expects a 100-continue response.

    Return Variable Data Type Description
    boolean
  • < InRequest > getEntity ( ) ( Entity )

    Get the entity from the inbound request with the body included

    Return Variable Data Type Description
    Entity
  • < InRequest > getHeader ( string headerName ) ( string )

    Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string
  • < InRequest > getHeaders ( string headerName ) ( string[] )

    Gets transport headers from the inbound request

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string[]
  • < InRequest > getMatrixParams ( string path ) ( map )

    Get matrix parameters from the request

    Parameter Name Data Type Description
    path string Path to the location of matrix parameters

    Return Variable Data Type Description
    map
  • < InRequest > getProperty ( string propertyName ) ( string )

    Retrieves the named property from the request

    Parameter Name Data Type Description
    propertyName string The name of the property

    Return Variable Data Type Description
    string
  • < InRequest > getQueryParams ( ) ( map )

    Gets the query parameters from the HTTP request as a map

    Return Variable Data Type Description
    map
  • < InRequest > setEntity ( Entity entity )

    Set the entity to inbound request

    Parameter Name Data Type Description
    entity Entity
  • < InRequest > getBinaryPayload ( ) ( blob )

    Gets the inboundrequest payload in blob format

    Return Variable Data Type Description
    blob
  • < InRequest > getContentLength ( ) ( int )

    Gets the Content-Length header from the inbound request

    Return Variable Data Type Description
    int
  • < InRequest > getFormParams ( ) ( map )

    Gets the form parameters from the HTTP request as a map

    Return Variable Data Type Description
    map
  • < InRequest > getJsonPayload ( ) ( json )

    Gets the inbound request payload in JSON format

    Return Variable Data Type Description
    json
  • < InRequest > getMultiparts ( ) ( Entity[] )

    Get multiparts from inbound request

    Return Variable Data Type Description
    Entity[]
  • < InRequest > getStringPayload ( ) ( string )

    Gets the inbound request payload as a string

    Return Variable Data Type Description
    string
  • < InRequest > getXmlPayload ( ) ( xml )

    Gets the inbound request payload in XML format

    Return Variable Data Type Description
    xml

public struct InResponse

Represents an HTTP Inbound response message

Field Name Data Type Description Default Value
statusCode int The response status code
reasonPhrase string The status code reason phrase
server string The server header
  • < InResponse > getEntity ( ) ( Entity )

    Get the entity from the inbound response with the body

    Return Variable Data Type Description
    Entity
  • < InResponse > getHeader ( string headerName ) ( string )

    Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string
  • < InResponse > getHeaders ( string headerName ) ( string[] )

    Gets the HTTP headers from the inbound response

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string[]
  • < InResponse > getProperty ( string propertyName ) ( string )

    Retrieve a response property

    Parameter Name Data Type Description
    propertyName string The name of the property

    Return Variable Data Type Description
    string
  • < InResponse > getBinaryPayload ( ) ( blob )

    Gets the inbound response payload in blob format

    Return Variable Data Type Description
    blob
  • < InResponse > getContentLength ( ) ( int )

    Gets the Content-Length header value from the inbound response

    Return Variable Data Type Description
    int
  • < InResponse > getJsonPayload ( ) ( json )

    Gets the inbound response payload in JSON format

    Return Variable Data Type Description
    json
  • < InResponse > getStringPayload ( ) ( string )

    Gets the inbound response payload as a string

    Return Variable Data Type Description
    string
  • < InResponse > getXmlPayload ( ) ( xml )

    Gets the inbound response payload in XML format

    Return Variable Data Type Description
    xml
  • < InResponse > setEntity ( Entity entity )

    Set the entity to inbound response

    Parameter Name Data Type Description
    entity Entity

public struct Options

Options struct represents options to be used for HTTP client invocation

Field Name Data Type Description Default Value
port int Port number of the remote service
endpointTimeout int Endpoint timeout value in millisecond (default value: 60000 milliseconds) 60000
maxActiveConnections int The maximum number of active connections the connector can create (default value: -1, indicates that the number of connections is not restricted) -1
keepAlive boolean Keep the connection or close it (default value: true) true
transferEncoding string The types of encoding applied to the request (default value: chunking) chunking
chunking string The chunking behaviour of the request auto
httpVersion string The version of HTTP outbound request
followRedirects FollowRedirects Redirect related options
ssl SSL SSL/TLS related options
retryConfig Retry Retry related options
proxy Proxy Proxy server related options

public struct OutRequest

Represents an HTTP outbound request message

  • < OutRequest > addHeader ( string headerName , string headerValue )

    Adds the specified key/value pair as an HTTP header to the outbound request

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value
  • < OutRequest > getEntity ( ) ( Entity )

    Get the entity from the outbound request

    Return Variable Data Type Description
    Entity
  • < OutRequest > getHeader ( string headerName ) ( string )

    Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string
  • < OutRequest > getHeaders ( string headerName ) ( string[] )

    Gets transport headers from the outbound request

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string[]
  • < OutRequest > getProperty ( string propertyName ) ( string )

    Retrieves the named property from the request

    Parameter Name Data Type Description
    propertyName string The name of the property

    Return Variable Data Type Description
    string
  • < OutRequest > removeAllHeaders ( )

    Removes all transport headers from the message

  • < OutRequest > removeHeader ( string key )

    Removes a transport header from the outbound request

    Parameter Name Data Type Description
    key string The header name
  • < OutRequest > setEntity ( Entity entity )

    Set the entity to outbound request

    Parameter Name Data Type Description
    entity Entity
  • < OutRequest > setHeader ( string headerName , string headerValue )

    Sets the value of a transport header

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value
  • < OutRequest > setProperty ( string propertyName , string propertyValue )

    Sets a request property

    Parameter Name Data Type Description
    propertyName string The name of the property
    propertyValue string The value of the property
  • < OutRequest > getBinaryPayload ( ) ( blob )

    Gets the outbound request payload in blob format

    Return Variable Data Type Description
    blob
  • < OutRequest > getContentLength ( ) ( int )

    Gets the Content-Length header from the Outbound request

    Return Variable Data Type Description
    int
  • < OutRequest > getJsonPayload ( ) ( json )

    Gets the outbound request payload in JSON format

    Return Variable Data Type Description
    json
  • < OutRequest > getMultiparts ( ) ( Entity[] )

    Get multiparts from outbound request

    Return Variable Data Type Description
    Entity[]
  • < OutRequest > getStringPayload ( ) ( string )

    Gets the outbound request payload as a string

    Return Variable Data Type Description
    string
  • < OutRequest > getXmlPayload ( ) ( xml )

    Gets the outbound request payload in XML format

    Return Variable Data Type Description
    xml
  • < OutRequest > setBinaryPayload ( blob payload )

    Sets a blob as the outbound request payload

    Parameter Name Data Type Description
    payload blob The blob representation of the message payload
  • < OutRequest > setEntityBody ( File content , string contentType )

    Sets the entity body of the outbound request with the given file content

    Parameter Name Data Type Description
    content File File containing the actual content
    contentType string Content-Type of the given data
  • < OutRequest > setJsonPayload ( json payload )

    Sets a JSON as the outbound request payload

    Parameter Name Data Type Description
    payload json The JSON payload to be set to the request
  • < OutRequest > setMultiparts ( Entity[] bodyParts )

    Set multiparts as the request payload

    Parameter Name Data Type Description
    bodyParts Entity[] Represent body parts that needs to be set to the request
  • < OutRequest > setStringPayload ( string payload )

    Sets a string as the outbound request payload

    Parameter Name Data Type Description
    payload string The payload to be set to the request as a string
  • < OutRequest > setXmlPayload ( xml payload )

    Sets an XML as the payload

    Parameter Name Data Type Description
    payload xml The XML payload object

public struct OutResponse

Represents an HTTP outbound response message

Field Name Data Type Description Default Value
statusCode int The response status code
reasonPhrase string The status code reason phrase
  • < OutResponse > addHeader ( string headerName , string headerValue )

    Adds the specified key/value pair as an HTTP header to the outbound response

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value
  • < OutResponse > getEntity ( ) ( Entity )

    Get the entity from the outbound response

    Return Variable Data Type Description
    Entity
  • < OutResponse > getHeader ( string headerName ) ( string )

    Returns the header value with the specified header name. If there are more than one header value for the specified header name, the first value is returned.

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string
  • < OutResponse > getHeaders ( string headerName ) ( string[] )

    Gets the HTTP headers from the outbound response

    Parameter Name Data Type Description
    headerName string The header name

    Return Variable Data Type Description
    string[]
  • < OutResponse > getProperty ( string propertyName ) ( string )

    Retrieve a response property

    Parameter Name Data Type Description
    propertyName string The name of the property

    Return Variable Data Type Description
    string
  • < OutResponse > getBinaryPayload ( ) ( blob )

    Gets the outbound response payload in blob format

    Return Variable Data Type Description
    blob
  • < OutResponse > getContentLength ( ) ( int )

    Gets the Content-Length header value from the outbound response

    Return Variable Data Type Description
    int
  • < OutResponse > getJsonPayload ( ) ( json )

    Gets the outbound response payload in JSON format

    Return Variable Data Type Description
    json
  • < OutResponse > getStringPayload ( ) ( string )

    Gets the outbound response payload as a string

    Return Variable Data Type Description
    string
  • < OutResponse > getXmlPayload ( ) ( xml )

    Gets the outbound response payload in XML format

    Return Variable Data Type Description
    xml
  • < OutResponse > setBinaryPayload ( blob payload )

    Sets a blob as the outbound response payload

    Parameter Name Data Type Description
    payload blob The blob representation of the message payload
  • < OutResponse > setEntityBody ( File content , string contentType )

    Sets the entity body of the outbound response with the given file content

    Parameter Name Data Type Description
    content File File containing the actual content
    contentType string Content-Type of the given data
  • < OutResponse > setJsonPayload ( json payload )

    Sets a JSON as the outbound response payload

    Parameter Name Data Type Description
    payload json The JSON payload object
  • < OutResponse > setStringPayload ( string payload )

    Sets a string as the outbound response payload

    Parameter Name Data Type Description
    payload string The payload to be set to the response as a string
  • < OutResponse > setXmlPayload ( xml payload )

    Sets an XML as the outbound response payload

    Parameter Name Data Type Description
    payload xml The XML payload object
  • < OutResponse > removeAllHeaders ( )

    Removes all transport headers from the response

  • < OutResponse > removeHeader ( string key )

    Removes a transport header from the response

    Parameter Name Data Type Description
    key string The header name
  • < OutResponse > setEntity ( Entity entity )

    Set the entity to outbound response

    Parameter Name Data Type Description
    entity Entity
  • < OutResponse > setHeader ( string headerName , string headerValue )

    Sets the value of a transport header

    Parameter Name Data Type Description
    headerName string The header name
    headerValue string The header value
  • < OutResponse > setProperty ( string propertyName , string propertyValue )

    Sets a response property

    Parameter Name Data Type Description
    propertyName string The name of the property
    propertyValue string The value of the property

public struct Proxy

Proxy struct represents proxy server configurations to be used for HTTP client invocation

Field Name Data Type Description Default Value
host string proxyHost: host name of the proxy server
port int proxyHost: host name of the proxy server
userName string proxyHost: host name of the proxy server
password string proxyHost: host name of the proxy server

public struct Retry

Retry struct represents retry related options for HTTP client invocation

Field Name Data Type Description Default Value
count int Number of retries
interval int Retry interval in millisecond

public struct SSL

SSL struct represents SSL/TLS options to be used for HTTP client invocation

Field Name Data Type Description Default Value
trustStoreFile string File path to trust store file
trustStorePassword string Trust store password
keyStoreFile string File path to key store file
keyStorePassword string Key store password
sslEnabledProtocols string SSL/TLS protocols to be enabled. eg: TLSv1,TLSv1.1,TLSv1.2
ciphers string List of ciphers to be used. eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
sslProtocol string SSL Protocol to be used. eg: TLS1.2

public struct Session

Represents an HTTP Session

  • < Session > getAttribute ( string attributeKey ) ( any )

    Gets the named session attribute

    Parameter Name Data Type Description
    attributeKey string HTTP session attribute key

    Return Variable Data Type Description
    any
  • < Session > getAttributeNames ( ) ( string[] )

    Gets the session attribute names

    Return Variable Data Type Description
    string[]
  • < Session > getAttributes ( ) ( map )

    Gets the session attribute key value pairs as a map

    Return Variable Data Type Description
    map
  • < Session > getCreationTime ( ) ( int )

    Gets the session creation time

    Return Variable Data Type Description
    int
  • < Session > getId ( ) ( string )

    Gets the session cookie ID

    Return Variable Data Type Description
    string
  • < Session > getLastAccessedTime ( ) ( int )

    Gets the last time the sessions was accessed

    Return Variable Data Type Description
    int
  • < Session > getMaxInactiveInterval ( ) ( int )

    Gets maximum inactive interval for the session. The session expires after this time period.

    Return Variable Data Type Description
    int
  • < Session > invalidate ( )

    Invalidates the session and it will no longer be accessible from the request

  • < Session > isNew ( ) ( boolean )

    Checks whether the given session is a newly created session or an existing session

    Return Variable Data Type Description
    boolean
  • < Session > removeAttribute ( string attributeKey )

    Remove the named session attribute

    Parameter Name Data Type Description
    attributeKey string Session attribute key
  • < Session > setAttribute ( string attributeKey , any attributeValue )

    Sets the specified key/value pair as a session attribute

    Parameter Name Data Type Description
    attributeKey string Session attribute key
    attributeValue any Session attribute Value
  • < Session > setMaxInactiveInterval ( int timeInterval )

    Sets the maximum inactive interval for the session. The session expires after this time period.

    Parameter Name Data Type Description
    timeInterval int Session max inactive interval

public function parseHeader ( string headerValue ) ( string , map , error )

Parse headerValue and return value with parameter map

Parameter Name Data Type Description
headerValue string The header value

public connector HttpClient ( string serviceUri , Options connectorOptions )

HTTP client connector for outbound HTTP requests

Parameter Name Data Type Description
serviceUri string URI of the service
connectorOptions Options connector options

Actions:

  • < HttpClient > delete ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    The DELETE action implementation of the HTTP connector

    Parameter Name Data Type Description
    path string Resource path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > execute ( string httpVerb , string path , OutRequest req ) ( InResponse , HttpConnectorError )

    Invokes an HTTP call with the specified HTTP verb.

    Parameter Name Data Type Description
    httpVerb string HTTP verb value
    path string Resource path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > forward ( string path , InRequest req ) ( InResponse , HttpConnectorError )

    Forward action can be used to invoke an HTTP call with inbound request's HTTP verb

    Parameter Name Data Type Description
    path string Request path
    req InRequest An HTTP inbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > get ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    GET action implementation of the HTTP Connector

    Parameter Name Data Type Description
    path string Request path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > head ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    The HEAD action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > options ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    OPTIONS action implementation of the HTTP Connector

    Parameter Name Data Type Description
    path string Request path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > patch ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    The PATCH action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > post ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    The POST action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError
  • < HttpClient > put ( string path , OutRequest req ) ( InResponse , HttpConnectorError )

    The PUT action implementation of the HTTP Connector.

    Parameter Name Data Type Description
    path string Resource path
    req OutRequest An HTTP outbound request message

    Return Variable Data Type Description
    InResponse
    HttpConnectorError

public annotation configuration

Configuration for HTTP service

Attribute Name Data Type Description
host string Host of the service
port int Port number of the service
httpsPort int HTTPS port number of service
basePath string Service base path
keyStoreFile string File path to keystore file
keyStorePassword string The keystore password
trustStoreFile string File path to truststore file
trustStorePassword string The truststore password
sslVerifyClient string The type of client certificate verification
certPassword string The certificate password
sslEnabledProtocols string SSL/TLS protocols to be enabled
ciphers string List of ciphers to be used
sslProtocol string The SSL protocol version
allowOrigins string[] The array of origins with which the response is shared by the service
allowCredentials boolean Specifies whether credentials are required to access the service
allowMethods string[] The array of allowed methods by the service
allowHeaders string[] The array of allowed headers by the service
maxAge int The maximum duration to cache the preflight from client side
exposeHeaders string[] The array of allowed headers which are exposed to the client
keepAlive boolean
transferEncoding string The types of encoding applied to the response
chunking string The chunking behaviour of the response
maxUriLength int Maximum length allowed for the URL
maxHeaderSize int Maximum size allowed for the headers
maxEntityBodySize int Maximum size allowed for the entity body
webSocket webSocket Annotation to define HTTP to WebSocket upgrade

public annotation resourceConfig

Configuration for HTTP resource

Attribute Name Data Type Description
methods string[] The array of allowed HTTP methods
path string The path of resource
consumes string[] The media types which are accepted by resource
produces string[] The media types which are produced by resource
allowOrigins string[] The array of origins with which the response is shared by the resource
allowCredentials boolean Specifies whether credentials are required to access the resource
allowMethods string[] The array of allowed methods by the resource
allowHeaders string[] The array of allowed headers by the resource
maxAge int The duration to cache the preflight from client side
exposeHeaders string[] The array of allowed headers which are exposed to the client

public annotation webSocket

Annotation to upgrade connection from HTTP to WS in the same base path.

Attribute Name Data Type Description
upgradePath string Upgrade path for the WebSocket service from HTTP to WS.
serviceName string Name of the WebSocket service where the HTTP service should upgrade to.

CONTENT_LENGTH

Attribute Name Data Type Description
CONTENT_LENGTH string Represent 'Content-Legth' header name