Practical tip about braces { } for new API documentation

[+Goldenhawk]

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.

[+Corfman Clan]

Have you been using the swagger for trying things out? I highly recommend it.

https://api.Groundspeak.com/api-docs/index

https://staging.api.Groundspeak.com/api-docs/index