New in version 6.2.0: See the new features.
Send a request to an HTTP server¶
http_simple_send() |
send a request to an HTTP server |
SYNTAX
http_simple_send(URL, Method, Options, RequestObject, ResponseObject)
This method sends a request to an HTTP server and waits for the response.
That function is used by the client side in a REST web service interaction.
URL |
The URL we send the request to (used to specify the remote resource to access or modify). |
Method |
The HTTP method, defined in the www.h header. |
Options |
Combination of HTTP_OPTION_ values defined in the www.h header. |
RequestObject |
Information to send to the REST service (web server), exactly the use and meaning of this argument depends on the Options value (see explanation below). |
ResponseObject |
It is used to specify what should be done with the response received from the REST service, this argument depends also on the Options value (see explanation below). |
RequestObject refers to the information sent to the web server into the message body, depending on the Options these are the possible meanings:
HTTP_OPTION_REQUEST_IS_FILENAME: The RequestObject is a filename which content will be the request content as is witout any transformation. RequestObject will be a filename specified in a literal string or a string field.
HTTP_OPTION_REQUEST_FILE_UPLOAD: The RequestObject is a filename that is going to be uploaded to the URL in a multipart/form-data POST. The file will be in a parameter called “File”. This option can be used when we want to send a file to store on the server, in this case the idea is not for the service to analise the file content (although it can obviously be done). RequestObject will be a filename specified in a literal string or a string field.
Otherwise RequestObject can be:
!record or ![o]file object, in which case the request body will be the record converted to JSON or XML depending on the value of sys.HttpRequestContentType.
Must be a string or a field (which will be converted to a string). The string is going to be sent in the body as is.
ResponseObject refers to the response received from the web server, depending on the Options these are the possible meanings:
HTTP_OPTION_RESPONSE_IS_FILENAME: The ResponseObject is a filename where the response content will be left.
Otherwise ResponseObject can be:
!record or ![o]file object, in which case the JSON or XML response (the exact value can be accessed in sys.HttpResponseContentType) will be parsed and copied in the record.
If it is a field the response content is assigned to it.
Note: When reading a JSON or XML response content the dimension of any array records defined with the RECFL_AUTOREDIM flag or array fields with the “a” flag are redim’ed to the size of the read JSON or XML object array.
The function returns the http status response value (Wikipedia) from the server (defined for convenience in http.h with prefix SC_), and a readable status message is accessible in the sys.HttpResponseMessage system variable. In case there is another error (not a web server returned error) the function returns -1 with an explaining message in the sys.HttpErrorMessage system variable.
EXAMPLE
This is an excerpt of a REST client example:
/********************************************************************************/
/* Data */
/********************************************************************************/
. Here we define the structure of the http://deckofcardsapi.com/api response
!record response {
deck_id,,a16,,v
remaining,,i4
shuffled,,i2
success,,i2
!record cards[1] {
value,"Value",a10
suit,"Suit",a10
code,"Code",a2
}
}
!temp numDraw,,i4
!temp numDecks,,i4
!temp shuffle,,i4
. Default number of decks, draw number and shuffle options
tmp.numDecks = 1
tmp.shuffle = 1
tmp.numDraw = 1
. Set the cards subrecord to autoredim. So it'll be resized to the returned size
response.cards->flags = RECFL_AUTOREDIM
...
!function fSendQuery(url) {
!temp status,,i4
. response !record array will be resized if needed
status = http_simple_send(url, METHOD_GET, 0, NULL, response)
. Check errors
if (status = -1) {
error "http_simple_send error: " + sys.HttpErrorMessage
return FALSE
}
if (status <> SC_OK) {
error "HTTP error (" + tostr(status) + "): " + sys.HttpResponseMessage
return FALSE
}
return TRUE
}
...
. URL: http://deckofcardsapi.com/api/deck/new[/shuffle]?deck_count=1
!function fQueryNew() {
!temp url,,a255,,v
!define DECK_API_BASE ""
url = "http://deckofcardsapi.com/api/deck/new"
if (tmp.shuffle <> 0) url = url + "/shuffle"
fSendQuery(url + "?deck_count="+tostr(tmp.numDecks))
}
/*------------------------------------------------------------------------------*/
. URL: http://deckofcardsapi.com/api/deck/<<deck_id>>/draw/?count=2
!function fQueryDraw() {
fSendQuery("http://deckofcardsapi.com/api/deck/" + response.deck_id + \
"/draw?count=" + tostr(tmp.numDraw))
}
...
RELATED TOPICS |