For different calls – let’s use the Publish a Post one for an example –, there’s a section for arguments that the call takes.
Are those arguments for the query string or are they meant to go in the JSON of the Body sent for the call?
Good question. Those arguments are meant to go in the JSON body of the call – this is true for all POST requests on the API.
For GET and DELETE requests, the arguments would go on the query string.
Ahh; gotcha. Thanks for the clarification!
I’m guessing this is so but just want to be 100% certain – does that mean the JSON in the body and the JSON returned will be different (like font and appearance seem to be the same values but font is listed as an argument while appearance appears in the example response JSON)?
No problem!
For the most part they’ll be the same. I believe these are the only property names that are different:
| Submitted | Returned |
|---|---|
| font | appearance |
| lang | language |
You can check out our go-writeas library for an official reference / example of the full set of properties the API allows (for example, Posts and Collections).
Awesome; good to know.
One last question, though on a different part of the API – I noticed you can grab all Posts related to a Collection but wasn’t able to find a call to grab all Collections related to a person’s account.
It’s always possible I missed it, of course, or is it expected for the application to be given which Collection to work from by the user?
That would be under the Retrieve User’s Collections section. We also have a way to get this information along with the returned data when a user authenticates, but the API isn’t finalized on it yet. So that’ll be another option in the future.
Once a user is authenticated, posts can be published:
- without supplying collection information, in which case they’ll be an anonymous / draft post (“draft” is the WriteFreely term)
- with collection information, in which case they’ll be added to that particular collection
So I didn’t yet thank you for the clarification you provided, mostly because I was excited to take that information and further finish my library to the API, so I just want to say thanks, again.
I did turn up another question. For publishing a post, does the call fail if a false token (say, “Token dhfhhdhdfhg” or some other token with the proper character length) is provided? I didn’t test it all that closely but it seemed that passing an empty string (i.e. "Authorization: ") was accepted so that the call was treating as creating an anonymous post but I was curious if an actually provided token would act similarly or fail.
No problem! What kind of library are you creating, if you don’t mind me asking?
I haven’t verified this, but I’m 99% sure posts will fail if a bad Authorization Token is given. Basically if it’s not an empty string, the server logic will assume you want to use the token for the request and do all the necessary checks. But we should make it so this happens whenever an Authorization header is passed in – thanks for bringing this up.
Gotcha. It should activate the authorizor every time since, even when it doesn’t have a token – yet –, it’ll send "Token "; just to be safe – though –, I have it call the login endpoint and save the token returned. So it’ll definitely be sending an incorrect token if it expires and trigger the authenticator.
I don’t mind, at all. It’s a Java library to interface with the API and make interacting with it a pure Java-objects experience. There’s two classes (one for endpoints which require authorization and one for endpoints that don’t) and you just pass the domain or domain, password, and username and then can just call methods that’ll make calls and return the response.
The current Java repository listed on the sites just has models and I’ve found myself numerous times in a situation of wanting to try building something for a service but not having enough experience or knowledge to take what resources were given and connect the missing dots. And I had some experient with Retrofit so I figured I’d try to see what I could do.
It’s at https://github.com/WammKD/Java-WriteFreely-API; still need to do, basically, all of the documentation but it’s basically done. I think the only thing I still need to fix is the authenticator isn’t getting triggered on 400 responses (but is, for example, on 401s). Otherwise – though –, it should be functional.
1 Like