Using the Web dropin (or calling a RESTful API from Oscript)

Hi,

I am hoping to call a RESTful API from Oscript, and I'm trying to avoid if possible using JavaObjects. Not that I'm intimidated by them, but I'm trying to limit the number of moving parts. I noticed that Oscript has a Web dropin defined, which seems to have what I'm looking for, and even provides for pulling a file from a RESTful service. Using the Web dropin, can someone explain what I would use for the context parameter besides a File or FileStream, if, say I was doing a call to https://someserver/api/authenticate to get back an authentication token, and how I would set it up as a POST (i.e. imagine I'm calling the OT REST API, although no, that's not what I'm doing)?

If this is seriously more trouble than it's worth, I'll go the JavaObject route, but then I'd ask how I'd return a file stream that was returned in a download request to the calling application to be streamed out to the user?

Thanks in advance

-Hugh

Find more posts tagged with

Comments

Greg_Griffiths

Hugh,

I have a link bookmarked - http://ednortonengineeringsociety.blogspot.co.uk/2009/08/creating-restful-web-services-with.html - which covered this, although I've just tried the link and it now requires you to be invited to the blog. Blogger does not give me the option to contact the author so can't ask for access

I did find a copy via Google at http://www.dullroar.com/creating-restful-web-services-with.html

Patrick Pidduck

I know it can be frustrating when I mention the future, but a teaser…

In CS16, there are utility functions available that facilitate making REST API calls from within OScript. We are using them internally for interacting with the Document Conversion Server, which has a new REST API supporting view as web page, MIME type detection, text and metadata extraction, document pattern matching, and thumbnail creation.

Patrick

From: eLink Entry: Content Server Development Forum [mailto:development@elinkkc.opentext.com]
Sent: Tuesday, December 15, 2015 8:35 AM
To: eLink Recipient
Subject: Using the Web dropin (or calling a RESTful API from Oscript)

Using the Web dropin (or calling a RESTful API from Oscript)

Posted by Griffiths, Greg On 12/15/2015 08:31 AM

Ben,

I have a link bookmarked -http://ednortonengineeringsociety.blogspot.co.uk/2009/08/creating-restful-web-services-with.html - which covered this, although I've just tried the link and it now requires you to be invited to the blog. I'll try and contact the originator to get acces

[To post a comment, use the normal reply function]
Topic:	Using the Web dropin (or calling a RESTful API from Oscript)
Forum:	Content Server Development Forum
Content Server:	Knowledge Center

HFCDev

Hi Greg,

I checked out the article, although it covers using Oscript for serving REST as opposed to consuming it. I decided to use my own Java class to do it so that at least I can use a known library (i.e. Apache's HttpClient). The only bummer is you can't directly stream a FileStream or Socket between Oscript and Java. You have to dump it out to a byte array.

-Hugh

Greg Griffiths

Can anyone point me to a code example for calling a REST API from within CS16 ? I've got code working similar to the above using Java, but would rather keep it all in OScript to ease maintainance for others.

Steve Brezina

Hi Greg,

Check out the new RestClient builtin in CS 16.0. It's what Patrick was alluding to in his earlier response. We use the RestClient to contact the DCS REST API for on demand content conversion.

See: $SystemObjEx.DocumentServerUtils.Request()

Regards,

Steve

Chris Meyer

Hi Steve,

Does RestClient only support POST and GET? Any way to do a PUT or DELETE? What about SSL connections?

Thanks Chris

Steve Brezina

Hi Chris,

Yes, just GET and POST are supported initially. SSL is anticipated to arrive in an update soon. The PM has been reminded about PUT and DELETE for completeness.

Steve

Donna Nalls

Hello Everyone,

I am using RestClient dropin and need to include cert and key files to my request. Using the API documentation, I see there is RestClient.AddAuthentication method, with a description of "Add a user and password/certificate for authenticating." -- I interpreted this as an option to pass certificate files....but, looking at the details, the method only includes input args for user UserName and Password.
Does anyone know if there is a way to pass cert and key files through the RestClient dropin?

Using Content Server 21.3, build 16.2.17.1604

Many Thanks,

Donna

-- ooohhhh, i just found it: NewSecure method has option for cert and key files! Thanks for all who would have responded!!!! :)

HFCDev

So does that mean that the REST client in Oscript is finally documented and supported? If so, this would be fantastic. In one project I've been resorting to http client. It works well, but a) it means maintaining extra JavaObject code, and b) it means that when you have proxies in the way, it's not a slam dunk for getting your service endpoints to work. b) is the bigger issue, because while I imagine RestClient probably reads from the Windows Cert Store, i.e. the same store that Content Server Oscript VM is using, your java object would be using the cacerts file in OTHome\jre\security instead. Not fun when you have multiple places to import ca certs.

-Hugh

Donna Nalls

Hi Hugh,

I found the documentation here:

https://knowledge.opentext.com/knowledge/llisapi.dll/fetch/-15106263/15106294/15106295/16376487/67794710/67790529/67838566/-/restclient.html?nodeid=67826320&vernum=-2

There is also an offline download

Donna

Donna Nalls

Hello Everyone,

I have hit an impasse with the rest client .newsecure method, passing the three additional args for certificate and key files.

client = RestClient.NewSecure( host, port, uri, timeout, certPath, certFile, keyFile )

The call above will return a new object...so, i believe it is correct. When i call client.Post(.....), i get a couple of different error messages. One message indicates one of my parameters is invalid or not supported. However, when i keep digging into the return data, i consistently see:

content =

{

"error": "invalid_request",

"error_description": "proper client ssl certificate was not presented"

}

I am pretty sure my paths to cert and key files are correct, as they work in Postman.

I'm wondering if anyone has had any success using NewSecure() with the cert/key files included -- any good advice would be greatly appreciated. Any bad advice would also be greatly appreciated. ;-)

Thanks,

Donna

HFCDev

Looking at the documentation, if you're on a Windows server, you should be able to leave the last 3 fields blank to get the drop-in to use the built-in Windows Security store. If you can rely on the built-in Windows store, that is usually the easiest. Postman always tends to be more forgiving, as what is rejecting the certificate is usually the client.

Are you using a service with a self-signed cert? That would be the main reason to use all three params (I think).

-Hugh

PS glad you're pioneering this because I think I'm going to have to convert an ospace currently using Apache HTTP client to use this instead so that the module and Content Server are always using the same cert store. So far hasn't been a problem except for cloud clients.

Donna Nalls

Hi Hugh,

Thanks for the response. First, I am, most assuredly, not pioneering anything here - just flailing around and wishing i could stumble upon an answer.

I have to use the cert and key file supplied by the vendor, so definitely have to include the last three args. The call to NewSecure does return an object - i would have thought it would not return an object if it did not validate the two files. Or, at least, give me a method to use to verify. :(

I'm sure the answer is me doing something stupid, but i just can't figure out what! :(

Donna

HFCDev

I decided to try this out as well. I'm not much further ahead, but I find the Rest client used quite a few times at least when calling OTDS. Perhaps someone from OpenText Engineering could (please, please, please) weigh in on how developers are supposed to be using this.

I tried a simple example using a URL endpoint that I know works when I call it from Apache Http client through a Java Object. So Apache HTTP client is able to resolve this. Here is my code (PS, why can I not switch to code format here like in stack overflow? this is supposed to be a developer's forum).

function void TestRESTClient()

String authURL = 'https://api.cognitive.microsoft.com/sts/v1.0/'

String svcEndpoint = 'api.cognitive.microsofttranslator.com'

Assoc headers

Assoc queryParams

RESTCLIENT rClient = RestClient.NewSecure(svcEndpoint, 443, "/sts/v1.0/issueToken")

String azureID = 'a working azure key I assure you'

headers.('Ocp-Apim-Subscription-Key') = azureID

Assoc chkVal = rClient.GET(queryParams, headers)

if (chkVal.ok)

echo("Successful")

else

echo(chkVal.errMsg)

end

Scheduler.DebugBreak()

end

The error message I get is SSL Exception: error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed

This is similar to the error that Donna is getting. Unlike Donna, I didn't bother specifying the extra parameters in RestClient.NewSecure(). I shouldn't have to for a public SSL address. I did a search in Oscript for RestClient.NewSecure() and the vast majority specify either 3 or 4 parameters (the 4th being the timeout).

Like Donna, I'm wondering what I'm doing wrong here. I even went for a far simpler example. I googled free API's for testing and found this one: https://api.publicapis.org/entries. I plugged that in, and got the same error. The only thing I can think of is that if you are calling RestClient.NewSecure() from CSIDE, you have an additional step to get it to point to the right certificate store. Can anyone from OT DEV tell me what that is? Given how widely used this drop-in is, I can't believe that it won't work elsewhere.

-Hugh

Hans Stoop

I would suggest that you check out how it is used by CS in the OTDS Integration or by WebReports.

Hans

HFCDev

That's exactly what I did. I can't easily test with OTDS on my sandbox as it's using the internal one on port 8002 which means I'm not trying the NewSecure() method because the internal OTDS runs on http. Both in OTDS and WebReports, every single invocation uses just 4 parameters - the hostname, the port (usually 443), a URI string (i.e /otdsws/rest), and possibly a timeout. Not a single use case using the extra certificate parameters that Donna noted (I can't speak for her, but I suspect that the vendor probably has a self-signed cert, meaning you'd need to add that certificate to a cert store which you explicitly reference). So far, I've never tried using CSIDE with an HTTPS instance so who's to say if the RestClient.NewSecure() method would break if CSIDE is not using the same cert store as the service.

Next I tried using it in a WebReport. There I constructed my report using this entry:

[LL_WEBREPORT_RESTCLIENT

@HOST:api.publicapis.org

@PORT:443

@SECURE:TRUE

@URI:'/entries'

@METHOD:'GET'

@TIMEOUT:10 /]

It returned {"errorMsg":"No context returned from GET call to /entries","success":false}

i.e. pretty much the same error I'm getting and similar to the errors that Donna is getting. So I ask again, what do we need to do to use this class if we're calling from inside CSIDE?

-Hugh

Donna Nalls

Hi Hans and Hugh,

Thanks to both of you for having a look.

Just to follow-up on Hans' suggestion, I did perform searches to find all references to NewSecure() in CSIDE, but none (not even otds) were using the cert/key file arguments. :(

I also have done much of what Hugh has attempted. I actually took the lazy route (for my proof-of-concept testing) and simply patched the RESTCLIENT tag to include the three extra args to NewSecure(). Yes, i do explicitly pass in the path to both cert and key files (which works in Postman).

As you say, Hugh, that "no context" error message seems to be a default of some sort - i find that if you grab "content" or the error messages, it will have a true value returned from the endpoint (if that's the correct terminology). This is when i see the ssl certificate error.

Thanks, again, for the responses. All are appreciated. I am still convinced that I'm doing something stupid...maybe you have proved me wrong and I will accept that as a bonus square in my life. :)

Donna

Donna Nalls

So, I just had another thought....could the dropin be having trouble opening the .pem and .key files?

hhhhmmmm....this might be it. these docs do not have an app associated with them. would that matter?

Hans Stoop

Hi Donna,

If it is not used like that in the standard code then it may not be as thoroughly tested. I would suggest that you contact support if you haven't already done that.

The other option I see is that you add your certificate to the standard CS certificate store.

Hans

HFCDev

@Donna, the experiment to try (I would do it but I'm on a train as I write this) is to see if the WebReport REST_CLIENT subtag works with a test API service (google free REST API's for example to get one that doesn't require authentication but uses SSL) when you're running as a service vs running normally. I have a sneaking suspicion that this dropin might break when called from CSIDE. Alternatively set up a DEV server that connects to an external OTDS running securely with a legit certificate.

I'd be curious to know if CSIDE is the thing that isn't working. If that's the case, I really want to know internally what workaround OT uses. To Hans' point, we probably need to import something into the cert store, but when you're calling a public REST API that has an externally verified cert, I mean, come on, that should just work out of box unless the DEV server has no way to contact Entrust, Verisign, etc.

@Hans, the reason why Donna, I, and others post here is because as Technology partners we can't open support tickets. This is also one that even if we could, we would need to get this to L3-L4 before we find anyone remotely able to help us, and it takes a long back and forth of "did you ensure that your computer is plugged in" to get there. I know this from a similar ticket I did work on through my government client, and even then, we had a hard time getting to someone in Engineering who understood such a nuanced problem.

For partners, literally this forum is it in terms of the support we are able to get.

-Hugh

Donna Nalls

Hi Hans, Hugh,

@Hans - I was also thinking this might be one of the "looks good in the documentation, but not thoroughly vetted by OT" situations. I have been holding hope that it was just me doing something stupid. I like the idea of moving the certificates to the CS certificate store...there may be an assumption in the dropin code for that. I did put the full path to the documents in my code, but didn't think to move the certificates into the CS certificate store - great idea!!! I will get with the client's system admin next week and ask him to do that!!!!

@Hugh - we are using the RESTCLIENT tag for other applications and it works perfectly fine. It's only when i am adding the additional args for the cert files that it fails.

Thanks, again, to both of you for the responses - greatly appreciated!!!

Donna

Hans Stoop

I understand Hugh.

The public API root should work.

I wrote a patch once for another project that used REST CLIENT in WRs, when WRs didn't support SSL. My patch simply always enabled SSL. They did not program anything with certificates, so I expect they went via a standard CA or added it to the store.

I can hardly believe that CSIDE is the issue, because the RESTCLIENT is also used with the core share integration and that is always a SSL connection.

Hans

HFCDev

Next I tried using it in a WebReport. There I constructed my report using this entry:

[LL_WEBREPORT_RESTCLIENT

@HOST:api.publicapis.org

@PORT:443

@SECURE:TRUE

@URI:'/entries'

@METHOD:'GET'

@TIMEOUT:10 /]

It returned {"errorMsg":"No context returned from GET call to /entries","success":false}

i.e. pretty much the same error I'm getting and similar to the errors that Donna is getting. So I ask again, what do we need to do to use this class if we're calling from inside CSIDE?

-Hugh

HFCDev

I'm revisiting this because I now have a need for it. It's either use RestClient or code something in Java to upload a multipart/form-data payload with a file whose content-type I may or may not know.

I still have yet to see this thing actually work. When run from CSIDE, I always get an SSL error regardless of whether I invoke with all the secure args or just the minimum (i.e. host, uri, port).

It errors always on the first GET or POST with an error like this

'message' : 'SSL Exception: error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed'

I assume that those who have got this to work have got it to work in CSIDE as well. That's where I'm running this. CSIDE should be using either the default Java keystore (in OTHome) or the Windows cert store, so I don't see why a regular public facing https URL would fail.

-Hugh

HFCDev

OK, this gets more mysterious....I tried two public API's - one for a GET and one for a POST, and both returned results, no SSL error. The URL I'm trying to connect to which is generating an SSL error is public facing, and when I checked it in Chrome, it shows up as being signed by Amazon (the one that worked was signed by CloudFlare). Does anyone know which cert store that the RestClient is using? If it's the Windows cert store, then there's no possible reason why the RestClient wouldn't recognize the cert. If it's the OTHome\jre\lib\security\cacerts, that might explain it. However, when executing our existing jar that we use for doing https requests, it works fine with the same URL that fails in RestClient.

I'm starting to think I simply cannot use RestClient.

-Hugh

HFCDev

One final question I need to ask on the whole RESTClient dropin. Can someone comment as to whether it is actually a wrapper around Apache HTTP client which OpenText ships?

-Hugh

HFCDev