Jump to content
Sign in to follow this  
Followers 0
Goldenhawk

Practical tip about braces { } for new API documentation

Recommended Posts

Due to the near-complete lack of examples in the API documentation, or anywhere else, I’ve been muddling through using the new API by trial and error.

The API documentation paragraph says things like “To use the access_token response value from either the token or the refresh token endpoint, add a header value. The header key should be Authorization and the value should be bearer {access_token}”. What I discovered this REALLY should say is “Use CURLOPT_HTTPHEADER or other methods to add an HTML header before sending the GET request” and VERY importantly, “don’t use braces around your actual values!” So I spent a lot of time trying to add a GET field like this:

https://staging.api.Groundspeak.com/v1/users/36149?bearer{123-234-234234}

https://staging.api.Groundspeak.com/v1/users/36149?bearer%20{123-234-234234}

https://staging.api.Groundspeak.com/v1/users/36149?bearer%20123-234-234234

before I finally discovered the documentation really did mean precisely use a true HTTP request header, and the space was necessary, but the braces were definitely NOT to be used. Very frustrating.

Same thing for the User Methods path of  “/v1/users/{referenceCode}” which really means use a GET link like /v1/users/12345678, not /v1/users/{12345678}. The same is true everywhere else that the braces {} are used around some parameter name or value... don't use the braces!

There’s nothing in the documentation anywhere that explains that the braces are used ONLY to show which items should be replaced with an actual value.

Share this post


Link to post

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Loading...
Sign in to follow this  
Followers 0

×
×
  • Create New...