I feel like this is a simple enough thing to do and can't believe how hard of a time I'm having finding the example I need so alas, human help please! You failed me Google :)
FYI I've written a bit of code in my life (Java, C, ASM, PHP), new to APIs.
As the title lays bare, I want to retrieve info (tickets out of our ticketing system meeting certain conditions) via a GET request, loop through each ticket, and update each one (PUT) based on certain conditions.
If there's a tutorial you know of that covers that, please point me to it! If not, if you could please fill in some of these holes?
I wound up in Postman, is this an appropriate environment to accomplish such? Of course you can make individual API calls here but I got lost trying to string the aforementioned sequence together. Is it possible via "Create API?" This makes it sound like I'm creating my own API server for other users to access data from. If it is possible via "Create API," where's the dang run code button?! If not Postman, what tool should I be using to write code in? And again, if you have any code samples/videos closely resembling said scenario for that tool.
Thank you for any assistance you can offer.
Cheers,
Jay
You want to interact with your ticketing system: read existing tickets, and update them. Correct?
To do this, your TICKETING SYSTEM must have an "api" (possibly - but not necessarily - a REST API).
If it does, you might be in luck. But you need to learn the API first, possibly from product documentation. If it doesn't, there's probably not much you can do except to interact with the system as a "normal user".
If it has an API, and if it's a relatively simple API (like REST), you can use the API manually (e.g. through POSTMAN), or you can use it programmatically (using Python, C#, Java or just about any programming language you feel comfortable with).
In summary, you need to:
Determine if your ticketing system provides any kind of web api
If so, get the API details
If at that point you want proceed, determine what programming language or framework you'd like to use.
Hopefully that gives you a bit of "direction".
In order to implement a CAPTCHA for my login page, I would like to understand how a translation test can be considered secure compared to popular image recognition patterns.
All customers will be bilingual speakers of an orally learnt and used Polynesian language i.e., no formal spelling conventions (hence the translation to English not the reverse), so instead of asking them to read distorted letters I would like to ask them to translate a simple sentence into English to be validated from the PHP server side.
Is this secure/accurate?
The basic idea to state that this kind of CAPTCHA ("Completely Automated Public Turing test to tell Computers and Humans Apart") is totally insecure is that while the OP states that "currently" Google Translator doesn't offer support for Polynesian language, it cannot be excluded that it will do so in the future.
More generally, translation is not a valid CAPTCHA test because of the following considerations:
Comparing a random sentence VS its automated translation using a public translator (e.g. a future version of Google, Bing) is equal for a hacker submitting the same phrase to the translation engine
Using a whitelist of sentences and their translations will be eventually overwhelmed by the accuracy of the automated public translators
I mean that modern public computer translators are perfecting their accuracy. If you assume that a public translator is unable to perform an accurate job today and challenge the user with a known phrase the translator cannot process, technology will tend to eventually fix that translation and you will get the challenge sentence easily spotted by robots.
That is the main principle of ReCaptcha being used as an OCR, but from the opposite side. I will suggest you to read this paper but briefly the researchers state that ReCaptcha is destined to improve its accuracy far more than automated OCRs because of user input.
Since Google and Bing Translate widely use user-submitted data to improve their translation process, they will be subject to a human-aided machine learning eventually breaking the Turing Test for that kind of challenge (e.g. ReCaptcha will read like a human, Translate will translate like a human)
After reading the comments, it seems the only danger I face is a vague future Google Translate one, which is unlikely to eventuate. So I'm going to stick my head out and say that this is indeed a good security measure which could conceivably be useful to many businesses or organisations that have such a customer base. Thanks for the assist.
Major point in it's favor is ease of use for the customers all of which so far prefer it to trying to read captcha. I put it on a live system so had 80+ people use it today.
I presume they all speak English too then? Unusual to require your users to be bilingual. Even if this is the case today, is it possible that with future growth you might be excluding certain users? What if someone moves into the area who wants to signup but only speaks English?
Language is a funny imprecise thing. You could take a sentence and probably translate it a number of different ways. Computers deal in precision so you need a question where there can only be one answer.
Also, the whole idea of a CAPTCHA is to make sure it's a real person but it may not be too hard to write a program that uses google translate or something similar. It may not always get it right but it'd probably get through some of the time.
If you've done any serious research into search API's, you know that most of them have a huge slew of TOS/TOU restrictions that make them nearly impossible to use in anything but the most inane applications.
Bing's 2.0 API, Yahoo Search BOSS, Google Places, Google AJAX Search (dead), et al, are far too restrictive for us. I need to run a finite and relatively small number of queries (perhaps 500k) one time only, storing specific data from the results for use within our application.
For example, we need to match up business names with their target websites (we have written the algorithm to make a 'best guess' from a set of results if necessary; we just need a vanilla result set). Also, we need to match an address to this company in question.
Unfortunately, I can find ZERO search API's that will allow us to fire off queries in a programmatic, non-user-initiated manner.
We're even quite eager to give someone cold, hard cash for access to this kind of data; Google, Bing, Yahoo, and others simply seem to not want our money (as evidenced by their TOSes)...
Any thoughts?
A freely accessible index of 5 billion web pages, their page rank, their link graphs and other metadata, hosted on Amazon EC2.
http://commoncrawl.org/
Their Terms of Service (or TOU) are pretty reasonable and unrestricted too:
http://commoncrawl.org/about/terms-of-use/
If you know some visual basic I'd suggest playing around with Bing Ad Intelligence. It's a free Excel plugin and all you need to use it is a free Microsoft account.
The query limit is 20,000 words per query. You can get information on Clicks, Impressions, CTR, CPC, Average Bid and Total Cost. The query limit is a little lower if you use the more advanced keyword research features.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html
Are use cases just multiple user stories??
What are the benefits of using user stories over use cases.. and vice-versa... When to use one over other...
Does all agile methodologies uses user stories??
Actually, the original use cases (see Jacobson's OOSE) were pretty lightweight, much as user stories are now. Over time, they evolved until a common format for "use cases" now is a complicated document with inputs, outputs, inheritance, uses relationships, pseudocode, etc. Programmers, in general, try to convert everything into programming.
In any case, the attempt to defined what distinguishes a "use case" from a "user story" fro a "scenario" is pretty futile, as it's hard to find two authorities who agree.\
Personally, I find the pattern "[Actor] [verbs] [noun] to get [business value]" helpful. If it gets over about a paragraph of text, it may be too big.
When it comes down to it "agile" is just a label, and people disagree over exactly what it means. Similarly people call very different things "use cases."
In my experience the primary difference between the two is that a user story is focused on the user, and is usually shorter and less formal - ideally, it should easily fit on a postcard. It probably doesn't give details of error handling etc.
Use cases can be much more formal (although some people write them informally too) - they focus on every interaction with the system, and may well go into more detail about several different systems/actors/etc within the same use case.
That's just my experience though - chances are everyone will have used these tools in different ways. I wouldn't get too hung up about labels - just use what works for your project.
Use cases aren't compilations of user stories.
User stories are generally much simpler than use cases. I think use cases try to cover absolutely everything to do with the behaviour of some aspect of the system. That is, all behaviours, all error paths and all exception handling.
The recommended template for a user is:
As a (role) I want (something) so that (benefit)
(Thanks Mike Cohn for providing this simple template)
Descriptions of behaviour expressed like this are more agile.
This sort of template lets you describe behaviour using different levels of detail. For example:
for those stories being implemented in a much later sprint, you can describe behaviour in a high level sort of way, e.g. as an ops team member I want to monitor the system remotely so that I can determine system health while on the road.
for those stories being implemented in the next sprint, you can describe behaviour is a slightly more detailed way, e.g. as an ops team member I want to have a dedicated ops only login so that I can check system health.
for those stories being implemented in the current sprint, you can describe behaviour in a highly detailed way, e.g. as an ops team member I want to have a web interface so that I can check current status of the ingest ftp server.
IMHO Use cases are much more carved in stone! And hence can be a problem to update after the initial version.
HTH
cheers,
Rob
In one word, no.
Use Cases are typically detailed specifications laying out how some particular piece of functionality is going to work, or how a specific user is going to utilize the system. It typically is in the voice of a specific user (or Actor) and is fairly self-contained.
A user story on the other hand is "an invitation for discussion". It is typically one or two sentences. Here is one good resource for that. And Mike Cohn's User Stories Applied is well worth it.
The typical syntax is "As a <user> I need <functionality> to achieve <business value>", or "To achieve <business value> as a <user> I need <functionality>" which drives home the value of the story.
User stories are not meant to be stand-alone, but meant to invite discussion of the story between the developer and the customer (or customer proxy).
You can think of a usecase as a user story, but not the other way around. A usecase will cover multiple "endings" to the story, special requirements (e.g. form fields must be entered in format xyz, and show error message 123 if the user enters a field in the wrong format). Also, a usecase can include additional references to external documents, such as security guidelines.
User Stories is a tool used in Agile development to make sure you create the product your user really needs.
It describes rather why you should make this or that feature instead of HOW or WHAT feature.
From my personal experience, it's a great way to balance the client's and developer's vision to create a better product.
Unlike US aUse Case focuses on WHO uses your product. Here is the difference.
I'd say there is no other such instrument for an Agile developer as User Stories. If you want to learn how to write them successfully, check out this post.