query parameters

[Jason Whitener]

I want to return the D2L internal userId for someone based on having their userName value.

GET /d2l/api/lp/(version)/users/ is what I assume I should use.  

This doesn't work:

URI uri = userContext.createAuthenticatedUri("/d2l/api/lp/1.4/users/", method); //creates the authenticated url.

String sUri = uri.toString() + "&userName=myUserName";  //tacks on the query parameter to the authenticated url.

String myResult = getHTML(sUri); //does the GET request

I also tried sticking the query parameter in the createAuthenticatedUri like URI uri = userContext.createAuthenticatedUri("/d2l/api/lp/1.4/users/?userName=myUserName", method);

What is the proper way to hand the query parameter value to D2L?  If I do a GET /whoami with the same code it works, so overall GET requests do process.  This is the first one I tried with a query parameter.

[Desire2Learn Staff: Sarah-Beth]

Hi Jason

We have an API Cookbook recipe that shows how to do a GET with the userName query parameter. Does that help with your understanding?

~S-BB

[Jason Whitener]

Not really. That cookbook shows the GET requests, but doesn't describe the code necessary to produce them using your client API's.  

[Jason Whitener]

In case anyone was wondering, it doesn't matter if you create the authenticated URL's with the parameters or add them later.  In my case, my error was a permission error on the API account.  

[Desire2Learn Staff: Viktor]

Jason, this is only true in one sense, but not true in another.

The query parameters of the API call are explicitly not part of the base string used for generating authentication tokens (signatures). The only reason that "it doesn't matter if you create the URLs with the parameters or add them later" is that our client SDKs can take care to strip off the parts it doesn't need in some cases.

For example, with the Python SDK:

• If you use D2LUserContext.create_authenticated_url(), then you must only provide the base path (API route) as an input parameter.
• If you have a complete API url in hand, and it's easier for your surrounding code to behave in that way, you can use D2LUserContext.decorate_url_with_authentication, and provide in the URL: it will decompose the path out of the URL and generate signature tokens as appropriate.
  

This can be very handy if you're working with API calls that return an "API URL" in a structure you retrieve (for example, some calls return paged data with an "API URL" that can get you the next, or preceding page of data) -- in these cases, you'd use the latter method, pass in the "API URL" you got from the back-end service (so you don't have to parse out the path yourself), and the SDK will decorate the URL with tokens appropriately for you.

If you include query parameters as part of the base string for forming authentication tokens, your code will explicitly not work properly -- the back-end service won't check the tokens with them, and you'll get an invalid token error.

--

Viktor

[Desire2Learn Staff: Viktor]

Your code looks like it will form the correct API call URL to make.

Things to check:

Does the back-end service support version 1.4 of the LP component's APIs? I suppose that it does, because you say you made a whoami call successfully.

What kind of error are you getting from the call? If you're getting a 404, then the service can't find a record that matches your user name, or it can't bind a handler to the route you provide at all (for example, if you use a version number the service doesn't support, or you have a spelling mistake in the route, or you forget a trailing slash when it should be there)--in this case, those latter cases seem unlikely, so if you're getting a 404, I suspect it's because the call can't find the user record to match your provided name.

Do you know the D2L ID of the user you're trying to bring back? If so, try fetching just that resource with GET /d2l/api/lp/1.4/users/(userId) and verify that the UserName property contains the user name that you expect to be searching upon.

Are you sure your user context is able to use this route to look at user records? Unlike whoami, this call is essentially in the administrative space (because it doesn't include an org unit ID in the route, it operates at the organization-wide level), so unless your user context has administrative permissions, it's unlikely you can use this call at all (or your use of it will be tightly restricted).

Keep in mind also that the UserName is a bit of personally identifying information and is subject to privacy controls: the user context making the API call must have permissions to see the user name property for users. (I believe that, if this is the problem, you'll get a 403 response when trying to use this call -- just as you would if you don't have permissions to use the API call to see user records at all.)