Documentation of token system for write API

[jywarren]

We now have a token system for people (or bots) to post comments via the API, thanks to @ryzokuken. We just need some documentation now!

API docs live here: https://github.com/publiclab/plots2/blob/master/doc/API.md and there's more work at #1449

We should document:

• where code lives
• example usage
• where tests are (this could be example usage, in fact)

Starting point here: https://github.com/publiclab/plots2/pull/1513/files

Thanks!

[namangupta01]

Hey @jywarren can i work on it?

[jywarren]

For sure, thank you!

[ryzokuken]

Sorry for not documenting the feature at that point in time as I was in a haste to complete the tasks on the timeline. Thanks for volunteering to work on it, @namangupta01! I would love to review it once you finish documenting.

[jywarren]

No problem at all! Teamwork!

[namangupta01]

@ryzokuken Thank you! :)

[namangupta01]

@jywarren @ryzokuken So i was working on this issue, i was wondering that do i only have to document about comments through token i.e https://github.com/publiclab/plots2/pull/1513/files ?

[ryzokuken]

@namangupta01 correct! This is the PR where I actually wrote the code for commenting through a token.

[stefannibrasil]

Hi, everyone! Can I help with this too? How is it going so far? I was thinking about start writing the token documentation to familiarize more with the API.

[ryzokuken]

@stefannibrasil I think this is abandoned for now, so you may feel free to go ahead and work on this. Let us know if you face any issues.

[stefannibrasil]

Thanks, @ryzokuken I am gonna start working on documenting the token feature this week. I am going to see some examples and I'll let you know anything, of course. Thanks for the help!

@sukhbir-singh do you wanna start working on this too? We can compare our work later.

[sukhbir-singh]

Yeah! sure 😄
@stefannibrasil you active on gitter??

[stefannibrasil]

HI @jywarren and @ryzokuken! After reading more the docs provided here, I have some questions to ask:

• The files in app/api/src/ folder are the docs that Swagger uses to generate the Interface, right?

• In order to generate the documentation for the token authentication, do I need to create a new file in the folder mentioned above, showing how the CommentController create action works?

That's what I understand so far. I would appreciate if you could give a little more information on that. Thanks!

[ryzokuken]

@stefannibrasil for saving time and effort, I had avoided making the "commenting over tokens" action a part of the existing Swagger API spec, and had made a standalone function in the Rails codebase (in CommentController, you're right) and made a route for that.

I don't think Swagger allows you to document external functions, but I might be wrong.
So, I believe you should just add some documentation by yourself in doc/api.md in markdown format, explaining a little how the function works and how we expect users to add their own comments using this endpoint.

I hope that makes it clear, feel free to ask for clarification on any of this.

[stefannibrasil]

That makes sense, thanks! After looking more at the docs and how to write API docs, I added some changes to this PR. I am not sure if that's the type of documentation you were asking for.

I added my questions in the description, could you please take a look and see if you can help me?

I couldn't find much documentation about the token, you can tell me where to look more too, that would help! :)

@sukhbir-singh sorry, I am not on gitter, but if you want, you can contribute in the PR too, that would be great.

[sukhbir-singh]

@stefannibrasil you can check out this video for demo showing how to use postman for making request on comment API. 🎈

[jywarren]

Great, is this complete, or is there more we could break out about this one? Feel free to close it up if it's done! Thanks, all!!!

[jywarren]

Actually perhaps we can add a couple additions -- like, could we refine POST https://publiclab.org/comment/create/token/id.:format to POST https://publiclab.org/comment/create/token/id.json to show you can specify the format like that. And maybe we should link to where the token API code is in the source?

https://github.com/publiclab/plots2/blob/master/app/controllers/comment_controller.rb#L48-L73

[ryzokuken]

@jywarren +1, that sounds perfect.

[stefannibrasil]

Hey, everyone! These are good points, thanks! The PR was already merged, I'll add this and create another one then =)

[stefannibrasil]

Also, thanks @sukhbir-singh thanks for all the help here!

[sukhbir-singh]

No problem...!! Happy to help. I am very active on github, gitter and irc, you can ping me there further if you need help in any case. 😃