Class HTTP

Used to retrieve the result of a URL.

Syntax

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

Constructors

HTTP()

Initializes a new instance of the HTTP class.

Declaration

HTTP

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

Methods

addAttachmentData(Integer)

Adds the binary data in the Service attachment specified to the body of the request.

Declaration

Bool addAttachmentData(Integer attachmentId)

Parameters

Type	Name	Description
Integer	attachmentId	The ID of the Service attachment you want to upload.

Returns

Type	Description
Bool	True if the attachment was found; otherwise, false.

Remarks

Must be used together with POST, PUT or PATCH.

Many REST endpoints expect the content to be uploaded as binary data when adding files. You can use this method for doing that. automatically set the Content-Type header based on the content type recorded in the database for the attachment. If you want to override the Content-Type, be sure to set a Content-Type header after doing the addAttachmentData call.

Examples

#setLanguageLevel 3;

HTTP http;

if(http.addAttachmentData(24))
{
  Byte[] res = http.post("https://httpbin.org/post");
  if (!http.hasError())
    print(String(res));
  else
    print(http.getErrorMessage());

addBinaryData(Byte[])

Adds the binary data to the body of the request.

Declaration

Void addBinaryData(Byte[] binaryData)

Parameters

Type	Name	Description
Byte[]	binaryData	An array of Bytes containing the binary data you want to apply to the request body.

Returns

Type	Description
Void

Remarks

Must be used together with POST, PUT or PATCH.

Many REST endpoints expect the content to be uploaded as binary data when adding files. You can use this method for doing that. Normally, you also want to add a Content-Type header, indicating what kind of files this is.

Examples

#setLanguageLevel 3;

HTTP http;
Byte[] image = http.get("https://httpbin.org/image/png");
if (!http.hasError())
{
  http.addBinaryData(image);
  http.addHeader("Content-Type", "image/png");
  Byte[] res = http.post("https://httpbin.org/post");
  print(String(res));
}
else
{
  print(http.getErrorMessage());
}

addDocumentData(Integer)

Add the binary data in the document specified to the body of the request.

Declaration

Bool addDocumentData(Integer documentId)

Parameters

Type	Name	Description
Integer	documentId	The ID of the document you want to upload.

Returns

Type	Description
Bool	True if the document was found; otherwise, false.

Remarks

Must be used together with POST, PUT or PATCH.

Many REST endpoints expect the content to be uploaded as binary data when adding files. You can use this method for doing that. automatically set the Content-Type header based on the extension of the document being added. If you want to override the Content-Type, be sure to set a Content-Type header after doing the addDocumentData call.

Examples

#setLanguageLevel 3;

HTTP http;

if(http.addDocumentData(24))
{
  Byte[] res = http.post("https://httpbin.org/post");
  if (!http.hasError())
    print(String(res));
  else
    print(http.getErrorMessage());
}

addHeader(String,String)

Adds a new header. The new header will be placed after other existing headers.

Declaration

Void addHeader(String name, String value)

Parameters

Type	Name	Description
String	name	Name of header
String	value	Value of header.

Returns

Type	Description
Void

Examples

HTTP h;

h.addHeader("header", "test");

Byte[] b = h.post("https://httpbin.org/post");

if (h.hasError())
print(h.getErrorMessage());
else
print(String(b));

delete(String)

Supports both HTTP and HTTPS.

Declaration

Byte[] delete(String url)

Parameters

Type	Name	Description
String	url	What to delete.

Returns

Type	Description
Byte[]	The result in a byte array.

Examples

HTTP h;

Byte[] b = h.delete("https://httpbin.org/delete");
if (h.hasError())
  print(h.getErrorMessage());
else

deleteAsStream(String)

Supports both HTTP and HTTPS.

Declaration

NSStream deleteAsStream(String url)

Parameters

Type	Name	Description
String	url	What to delete.

Returns

Type	Description
NSStream

Examples

HTTP h;

NSStream b = h.deleteAsStream("https://httpbin.org/delete");
if (h.hasError())
  print(h.getErrorMessage());
else

get(String)

Supports both HTTP and HTTPS.

Declaration

Byte[] get(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
Byte[]	The result in a byte array.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
Byte[] b = h.get("https://httpbin.org/get");
if (h.hasError())
  print(h.getErrorMessage());
else

getAsStream(String)

Supports both HTTP and HTTPS.

Declaration

NSStream getAsStream(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
NSStream	The result.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
NSStream b = h.getAsStream("https://httpbin.org/get");
if (h.hasError())
  print(h.getErrorMessage());
else

getDebug()

Retrieves debug output.

Declaration

String getDebug()

Returns

Type	Description
String	The debug output.

Remarks

Turn on debug mode by calling setDebugMode(true) before you use getDebug().

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

getErrorMessage()

Returns the last error message.

Declaration

String getErrorMessage()

Returns

Type	Description
String	The last error message.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
Byte[] b = h.put("https://httpbin.org/put");

if (h.hasError())
  print(h.getErrorMessage());
else

getResponseHeader(String)

Gets a named HTTP header from the response of the HTTP request.

Declaration

String getResponseHeader(String header)

Parameters

Type	Name	Description
String	header	The header to get.

Returns

Type	Description
String	The header.

Remarks

Case insensitive.

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

getResponseHeaders()

Gets a map of all the headers from the HTTP response headers after making a HTTP call.

Declaration

Map getResponseHeaders()

Returns

Type	Description
	A map of all the headers from the HTTP response headers after making a HTTP call.

Remarks

The key is in lower case regardless of what was returned by the response. The value will keep the case.

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

getValue(String)

General function which returns various values from the instance.

Declaration

String getValue(String name)

Parameters

Type	Name	Description
String	name	What to get (statusCode).

Returns

Type	Description
String	Values from the instance.

Remarks

statusCode: Will return the status code from the HTTP request (such as 404, 200). Supported from v8.0sr3.

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

hasError()

Checks if there was an error in the environment.

Declaration

Bool hasError()

Returns

Type	Description
Bool	True if there was an error in the environment; otherwise, false.

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

open(String)

Opens a URL and returns the result as a Byte array.

Declaration

Byte[] open(String url)

Parameters

Type	Name	Description
String	url	The URL to open. http://...

Returns

Type	Description
Byte[]	Result as a Byte array.

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");

if (h.hasError())
  print(h.getErrorMessage());
else

openAsStream(String)

Opens a URL and returns the result as an NSStream.

Declaration

NSStream openAsStream(String url)

Parameters

Type	Name	Description
String	url	The URL to open. http://...

Returns

Type	Description
NSStream

Examples

HTTP h;

NSStream b = h.openAsStream("https://httpbin.org/");

if (h.hasError())
  print(h.getErrorMessage());
else

patch(String)

Supports both HTTP and HTTPS.

Declaration

Byte[] patch(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
Byte[]	The result as a byte array.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
Byte[] b = h.patch("https://httpbin.org/patch");
if (h.hasError())
  print(h.getErrorMessage());
else

patchAsStream(String)

Supports both HTTP and HTTPS.

Declaration

NSStream patchAsStream(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
NSStream	The result.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
NSStream b = h.patchAsStream("https://httpbin.org/patch");
if (h.hasError())
  print(h.getErrorMessage());
else

post(String)

Supports both HTTP and HTTPS.

Declaration

Byte[] post(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
Byte[]	The result as a byte array.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
Byte[] b = h.post("https://httpbin.org/post");
if (h.hasError())
  print(h.getErrorMessage());
else

postAsStream(String)

Supports both HTTP and HTTPS.

Declaration

NSStream postAsStream(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
NSStream	The result.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
NSStream b = h.postAsStream("https://httpbin.org/post");
if (h.hasError())
  print(h.getErrorMessage());
else

putAsStream(String)

Supports both HTTP and HTTPS.

Declaration

NSStream putAsStream(String url)

Parameters

Type	Name	Description
String	url

Returns

Type	Description
NSStream	The result.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
NSStream b = h.putAsStream("https://httpbin.org/put");
if (h.hasError())
  print(h.getErrorMessage());
else

setDebugMode()

Turns debug mode on/off to record debug output.

Declaration

Void setDebugMode(Bool debug)

Parameters

Type	Name	Description
Bool	debug	True to turn debug on, false to turn it off.

Returns

Type	Description
Void

Examples

HTTP h;

Byte[] b = h.open("https://httpbin.org/");
printLine(h.getValue("statusCode"));

if (h.hasError())
  print(h.getErrorMessage());
else

setOption(String,Bool)

Option function.

Declaration

Void setOption(String name, String value)

Parameters

Type	Name	Description
String	name
String	value	See table.

Returns

Type	Description
Void

Remarks

>>>>>>>>>

Value	Description
verifyPeer	verify the peer's SSL certificate
verifyHost	verify the certificate's name against the host
timeout	set maximum time the request is allowed to take
followLocation	follow HTTP 3xx redirects if set to 1, default is 1
username	username used in authentication
password	password used in authentication
parameters	The complete parameters to post. This will replace whatever you have added using .setValue(), but allows you to specify the whole parameter to post. Useful when posting e.g. JSON structs instead of name=value pairs. NOTE you need to prefix whatever you want to send with a dummy character (which will be removed) due to complexities in this class. See the example below.
authenticationMethod	which authentication method to use basic (default), digest, gssnegotiate, ntlm, digest_ie, ntlm_wb, none
parametersUTF8	From version 8.2R3. This option makes the parameters be encoded as UTF-8. Normally this is what you want, but to not break any old uses, this is an optional option.

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");

Byte[] b = h.post("https://httpbin.org/post");

if (h.hasError())
  print(h.getErrorMessage());
else
  print(String(b));

//Here is an example for creating an issue in JIRA, hosted by Atlassian

HTTP h2;
String json = " {
  "fields": {
    "project": {
      "key": "SUP"
    },
"summary": "I have a problem!.",
"description": "Thats awesome",
    "issuetype": {
      "name": "Bug"
    }
  }
}";

HTTP h;
h.setOption("username", "theUsername");
h.setOption("password", "thePassword");
h.addHeader("Content-Type", "application/json");
h.setOption("parameters", json);
print(String(h.post("https://theInstance.atlassian.net/rest/api/2/issue/")));

setValue(String,String)

Adds a CGI variable and its according value to the HTTP request.

Declaration

Void setValue(String cgiVariable, String value)

Parameters

Type	Name	Description
String	cgiVariable	The variable to set
String	value	The value.

Returns

Type	Description
Void

Examples

HTTP h;

h.addHeader("header", "test");
h.setValue("key", "value");
h.setValue("key2", "value2");
h.setOption("followLocation", "true");
Byte[] b = h.put("https://httpbin.org/put");
if (h.hasError())
  print(h.getErrorMessage());
else