It would be nice to have examples for requests as well, and not just for replies. For instance, there is no example what string would be passed to the "language" post key. It may be trivial, but there is only a reference now to a somewhat complex backend. End users do not care much about what backend a server uses. :-) They would like to know what the server expects, and examples are good for that like in other RESTful APIs because they make it self-contained and comprehensive. For instance, if it is mentioned that is is "language=c++", people will know off-hand, if they need to use python, they need to pass "language=python" as a first try. If that does not work, they only go to the more thorough documentation afterwards for details. Thank you for the spec and work, by the way. :) Reproducible: Always
Oh, and while I am at it, is there a maximum size for the paste content uploaded? I was considering having to apply some chunk transfer to reduce the memory usage on the client side, but if it is negligible, it is not worth it. If you can guarantee something for this, I would extend the spec documentation with that information as well.
Furthermore, I know it is somewhat unreal, but shows my lack of understanding in this area, I have not known for a while how to request through post data. One person even said that "key1=value1&key2=value2" may be acceptable, but it is not. :) I would consider giving a json, and also xml example to the spec readers. It is just a few lines, but it is worth to avoid confusion. As for me, it was not clear immediately if the post data is some standard format like the one aforementioned. Perhaps, I was too much led by the get method, but still clarity would avoid all this, and it does not take much, and if there is an example with the mandatory parameters, and maybe one with an optional, it is explicitly very clear then, and it does not bloat the documentation much either in my opinion.
The project parameter is also somewhat unclear. As it seems the paste.kde.org web client does not implement that parameter, hence we cannot obtain ideas from there either. Next issue: private: Whether the paste is private or not (1 or 0) I would prefer to use "true" or "false" (i.e. boolean) there, especially for JSON.
I have an example client here: https://github.com/sayakb/sticky-notes/tree/api-client The language parameter is what GeSHi supports. I wanted to document that but it is a huge list and it keeps changing. I have a plan to add an endpoint in the API itself that will let you get a list of supported languages. Easiest way to find for now is to view the sandbox.paste.kde.org HTML source and look for name="language" - all option "values" are valid parameters. Currently, the max paste size is 64KB. I wanted to make it 16MB, but the framework I use does not support that datatype (mediumtext) right now. I'll check with the Laravel folks on this. You can do a CURL to the API create endpoint and set the HTTP method as POST (-X POST). Depending upon where you do "key1=val..." (in the URL or in the POSTdata), you can treat the method as acceptable or unacceptable. Sending as URL parameters will not work anyway as I have disabled GET parameters as we might be sending sensitive information like passwords. Check out the implementation example if it helps. The project parameter has been explained here: http://sayakb.github.io/sticky-notes/pages/services/ - but note that this doc will tell you how sandbox.paste.kde.org will implement it (currently not set up to do so). Paste.kde.org with v0.4 of the pastebin had a different way of handling projects (as explained here: http://fpaste.org/doc/help/#projects - giving you the fpaste link as i will move paste.kde.org to the new version any day now).
This was given to me by one of the users - fetched it from my IRC logs. Maybe this helps? echo "curl test" | curl -v -H "Content-Type: application/json" -X POST -d "{\"data\": \"$(</dev/stdin)\", \"language\": \"text\"}" http://cpaste.org/api/json/create 2>&1
Thank you for your reply. A) Language In general, the spec should define all the acceptable input values, but if it is tricky for some reason, a good start would be to give a pattern. Which one of the following forms does it accept? * c++ * cpp * C++ (case sensitive?) * c-++ * lang-c++ * c++-lang * _Cpp_ * _c++ * etc Even though I can probably hunt this data from elsewhere, it would be nice to at least document the pattern in the spec. :) B. Maximum size Someone told me 8 MB based on post_max_size PHP coniguration, but I am fine with any of those maximum sizes as of now. It would be nice to put the maximum size as a hint at least into the documentation so that the application developers can design their client software accordingly. Maximum size decides whether it is worth supporting chunk transfer or mmap for memory starving. Would it be possible to put it into the specification? C. Post data format I used " curl -i -X POST -H "Content-type: application/json" -d '{"data":"bla-bla-bla","language":"c"}' http://sandbox.paste.kde.org/api/json/create" myself, but I am not about to solve the problem for myself only here. I am proposing to make the spec more self-explanatory in certain aspects. I would not mention "curl" in the spec for two reasons: * It will not work for windows users off-hand. * Many people do not know how to use curl, and they would need to start reading curl documentation even though they only need the data format. * I think providing the data is comprehensive. D. Boolean parameter What do you think about the boolean idea? I think it would be worth changing the new API for that bit, but at least for the json part. If it is hard because there are many users of the new API, I would suggest obsoleting 0 and 1 while keeping it around for a bit. That way, we could introduce the alternative parameter type already for now while keeping compatibility for a reasonable time which is enough for the users to switch away to the new parameter type.
I unfortunately cannot add the language list to the spec. Currently 222 languages are supported and the list keeps piling up. It is not possible for me to maintain the list. I'll work on the language endpoint in the next version. For your reference, you can either check the method I suggested to get the language codes (From HTML source: <option value="cpp">C++</option> - so "cpp" is the correct choice). I do not control these options as I need to use what GeSHI uses. You can also see here: http://qbnz.com/highlighter/examples.php - hover on the language to get the name. This is just a temporary solution till I add the language list endpoint. I'll add the spec documentation modifications to my list. However, it is an OSS repo, so feel free to send a merge request on github ;) As of true/false, it makes no difference as PHP is not strongly typed. So it will treat true/false same as 1/0 - I can update the specs to reflect that later. However, I do need to make some change to the code as it currently only checks whether the parameter was passed (and not the actual value). I'll make that code change tomorrow.
CURL is just one way of sending the data. The api-client example I use does not use CURL at all. I can include some JSON request samples later though - cannot promise you an ETA as I am currently dealing with some serious health issues here - which even made me miss my 10/1 deployment deadline for paste.kde.org
I need to correct my response here. PHP interprets POSTdata as all string unfortunately :( So here is what I'll do: set private to anything (true or 1 or hakunamatata) and it is set as private. For public pastes, simply do not send the private param at all. That works for you?
OK, thank you for your reply. I would have sent patches, but unfortunately I do not know where I can find the source code of the API site: http://sayakb.github.io/sticky-notes/pages/api/ "language: The development language used (click here to see supported languages)" -> I would replace the link here with the one you provided: http://qbnz.com/highlighter/examples.php I agree that a language query GET method would be nicer in the future. I agree that having a default value "no" for the private parameter is good enough. However, I would still call it as true and false. That is a json boolean type as well. I am surprised if php based json parsers cannot handle such a string in the good manner. If that is the case, that is unfortunate. I am sorry to hear you have health issues. Sorry for questions and comments then. Hope, you recover soon. Having health issues is unfortunate, I know myself. Hopefully, this is just a short interim period for you. :)
I have updated the language link on the site. I'll try to work on the language endpoint this weekend if health gets better. Unfortunately, if you set it as false, the only way for me to check a non-boolean would be $data['expire'] === 'true' - which is ugly :-/ However, I do agree that true should still replace 1, so I have changed the specs doc to reflect that.
OK, thanks! One additional question from here: http://www.sayakbanerjee.com/2013/09/16/new-paste-kde-org-api-specs/ "You can test out the new version of the API here: http://sandbox.paste.kde.org/" -> That url is not available at the moment. Have you migrated to cpaste.kde.org which you mentioned above with the curl command, or it is supposed to work?
cpaste is run by someone else. You can use pastebin.kde.org (*not* paste.kde.org).
OK, thanks. "cutepaste" is now working with one feature: creation. :) lpapp ~/Projects/kde/cutepaste $ cat Mainpage.dox | ./a.out http://sandbox.pastebin.kde.org/p7l6ugmhn lpapp ~/Projects/kde/cutepaste $ ./a.out Mainpage.dox http://sandbox.pastebin.kde.org/pxvqas3do
This is great! I'll close this report as resolved. Please create a new ticket on GitHub for any questions/issues if I'm not reachable on IRC. Thanks for working on this! :)
OK. :) There is one additional note I discovered while debugging the application: the reply seems to contain a "result" root json object in which the "id", "hash", etc keys can be found. Perhaps, this could be made clear in the api spec as well.