Help understanding cURL

[gwilburn]

Working with a new RESTFul API... The API is used to retrieve a PDF document based on the "parameters" sent. All of their examples are written in cURL syntax.

I've been provided a 32-character API "key". Here is one of the "tests"

curl --request GET \
--url https://dev-staging.companyname.com/...me/packingslip \
--header 'accept: application/pdf' \
--header 'apikey: 189f976876194069ac9f72eb30c62867'

In production, the call to the API is documented like this (where QUERYSTRING contains the "&order=12345" etc.)

curl --request GET \
--url https://dev-staging.companyname.com/...ne?QUERYSTRING
--header 'accept: application/json' \
--header 'apikey: 189f976876194069ac9f72eb30c62867'


So I'm using HTTPAPI and http_url_get to basically do the same thing.
1. I base64-encoded the API key
2. Established the easiest "test" URL
3. Then: rc = http_setauth(http_auth_basic
:%trim(apiUser)
:%trim(token64));
rc = http_url_get( URL
: Stmf // output file
: HTTP_TIMEOUT
: HTTP_USERAGENT
: modtime
:'application/json');

But I'm not sure exactly where to put the "header" stuff...
1. With previous APIs I have used the HTTP_SETAUTH to provide a key.
2. Assuming I'm changing the content-type with the 6th parameter passed via HTTP_URL_GET ('application/json')


Any help would be appreciated as my knowledge in this area is limited.

[Scott Klement]

Hmmm... I saw the subject line and thought "that's strange, why would he ask about cURL in the RPG forum?" But, I see your question is really about HTTPAPI not cURL, so now it makes sense.

I'm not sure I understand the part about base64 encoding the key, or why you're setting it as a password? That seems strange to me.Using http_setAuth() is equivalent to passing the -u or --user option to cURL, which you didn't do in the cURL example. So either this is something you are doing wrong, or it is something you just didn't mention was necessary when you showed the cURL option.

Anyway, to set your own custom headers in httpapi, you have to use an "exit procedure". Setting HTTP headers is a rather unusual thing to do, in fact a lot of HTTP clients don't even have an option for it -- but cURL does, and so does HTTPAPI, so you should be able to make it work. The way HTTPAPI does it is just a bit different -- instead of specifying the headers in advance as parameters like cURL does, HTTPAPI lets you define a subprocedure that is called at the moment when the headers need to be sent to the server. So you can add your own "additional headers" at that time. A little weird, perhaps, but I did it that way because it was easy for me to code. You'll need to format the headers according to HTTP spec, but that's easy enough to do since they are just text strings with CRLF at the end.

Here's a program I already had (sorry about the older RPG style) that I've adapted a bit to match your cURL example:

     H dftactgrp(*no) actgrp(*new)
     H bnddir('HTTPAPI') option(*srcstmt)

      /define WEBFORMS
      /copy httpapi_h

     D addSpecialHeaders...
     D                 PR
     D   headersToAdd             32767A   varying
     D   vars                              likeds(headerVars) const

     D OrderNum        s              5p 0 inz(12345)
     D

     D headerVars      ds                  qualified
     D   acceptType                 100a   varying
     D   apikey                     100a   varying

     D form            s                   like(WEBFORM)
     D url             s           1000a   varying
     D rc              s             10i 0

      /free

       // Turn on debugging -- probably want this to be *OFF
       //  when in production.

       http_debug(*on);


       // Create a URL with a properly encoded query string:

       form = WebForm_open();
       WebForm_setVar(form: 'order': %char(OrderNum));

       url = 'https://dev-staging.companyname.com/...me?'
           + WebForm_getData(form);

       WebForm_close(form);


       // Tell HTTPAPI to use an "exit procedure" that is a subprocedure
       // called when it's adding headers to the URL.  Pass the API
       // key and content-type to accept to the exit procedure when
       // the time comes.

       headerVars.acceptType = 'application/json';
       headerVars.apiKey     = '189f976876194069ac9f72eb30c62867';

       http_xproc( HTTP_POINT_ADDL_HEADER
                 : %paddr(addSpecialHeaders)
                 : %addr(headerVars) );


       // Perform a GET request and save the result to a file in the IFS.

       rc = http_get( url: '/tmp/result.txt' );
       if rc <> 1;
         http_crash();
       endif;

       *inlr = *on;

      /end-free


     P addSpecialHeaders...
     P                 B
     D                 PI
     D   headersToAdd             32767A   varying
     D   vars                              likeds(headerVars) const

     D CRLF            C                   x'0d25'
      /free
         headersToAdd = 'accept: ' + vars.acceptType + CRLF
                      + 'apikey: ' + vars.apiKey + CRLF;
      /end-free
     P                 E

So this demonstrates a few things:

1) How to properly encode/add a query string.

2) How to set headaers with http_xproc().

3) How to use http_get (which is the same as http_url_get, just a shorter name)


Note that the 'addSpecialHeaders' procedure can be called any name you like -- as long as the %paddr() matches the same name. Likewise, the 'headerVars' data structure can be anything you want, you can change the variables in it however you like, as long as it matches the corresponding %ADDR() and LIKEDS code used in the program.

[gwilburn]

Thanks Scott... You are correct... it may be my misunderstanding. I thought i read somewhere that the API key they provided me should be encoded. Hopefully I can find some time this week to give this a try... was out of the office the end of last week.

[gwilburn]

...as a follow up

Once I figured out their documentation, this worked perfectly. Thank you Scott!!

It seems like the biggest challenge is understanding the documentation for some of the APIs we encounter. I know it's probably due to my lack of understanding of other languages/methods. But I'm not sure how to overcome that.

Thanks again for your insight.
Greg