Best Practices, Tips, and Ideas for Creating Custom Client Applications with Tenon API

We get a lot of traffic coming through Tenon’s demo page, also known as "Test Now", but the best use of Tenon is with the API. When talking about Tenon, we often say we’re API first. Everything we do on Tenon.io that performs testing is in itself an API client application. You can see some of that stuff over in our public Bitbucket repos. We also have a page dedicated to others’ contributions on our site. We encourage our developer community to make new stuff with Tenon API. Together we can make accessibility testing less painful. Here are some best practices for making an excellent application with Tenon API:

Don’t hard-code your API key into the application

You should allow the API key to be set either in some sort of custom settings page or an environmental variables file. Hard coding the API key is bad for a few reasons:

  • All API traffic is tied to the API keys. Put simply, if you hard code your key, you’re the one who gets charged for other people’s usage.
  • You or your application’s users might want to change the key at some time in the future.

Andrew Bababian’s grunt-tenon plugin allows users to pass in their API key as part of the tasks’s options. We definitely recommend doing something like that or, even better, creating a global settings file that could be shared.

Retain Tenon’s Flexibility

Similar to the above, you should allow your users to enter their own request parameters at least as a global setting for the app itself. Tenon offers a lot of request parameters that make it very easy to customize how Tenon tests. Let your application’s users make these choices for themselves.

Don’t store error information

By all means, store the issue results themselves, but we recommend against parsing the results to save the issues’ text content for later use, separate from the issues themselves. Certain parts of the issue reports are subject to change at any time. Tenon’s tests are not tied to our release cycle and may be revised or improved without notice. Some things, just as a test’s ‘certainty’, ‘errorDescription’, etc. may be adjusted on the fly as part of our continuous effort to make things better and better.

Tips for an even better application

  • If your application allows outside input, validate the input before sending the request to Tenon. It’ll make the application faster for the user.
  • If you’re planning on building a Grunt task or Node module, we recommend an option that allows it to return true or false as well as an option that lists results (or both). This way your users can use your application automated test/ build/ deploy systems.
  • If you want to provide a way to test page source, you should still try to somehow include all CSS and JS assets. Some ideas include using Grunt HTML Smoosher to inline the external contents. Another idea would be to render the document in PhantomJS and grab the document’s full rendered DOM with JavaScript.
  • We think it makes sense to group issues. You can group things by bpID (Best Practice ID, there may be multiple tests for each best practice), and tID (Test ID, the specific test failed). Grouping the results will make it easier for your users to understand.
  • If you offer the ability to sort results, we recommend adding the ability to sort by Priority and Certainty. (See: Understanding Issue Reports)
  • Make use of the issue signature. The issue signature is an MD5 hash of the specific issue. If your application allows users to test multiple pages, you can use the issue signature to ensure you’re only reporting the issue one time, even if it exists on multiple pages. Another idea might be to list the issue and then also list each page it exists on.

Application Ideas

One of the main reasons we’ve chosen to go “API First” is for the freedom and flexibility it offers. Here are some of the cool ideas we’d like to collaborate on with our community:

  • Content checking for Content Management Systems. Systems like WordPress and Drupal have millions of users. You can help make a huge impact on web accessibility by creating an Admin plugin that grabs only the content and submits that to Tenon.
  • Plugins to CKEditor and TinyMCE. Similar to above, these two editors are everywhere. A standalone plugin for the editor, rather than the CMS would be in high demand.
  • Report conversion to jUnit/ xUnit report format. Loads of systems use this format, such as Jenkins, Ant, and Bamboo.
  • Plugins for various browser’s DevTools. Chrome and Firefox both have pretty user-friendly APIs for extending their DevTools.
  • IDE Plugins. Sublime Text, Webstorm, Aptana, Eclipse, Netbeans, etc. all have pretty robust plugin ecosystems.

Finally, feel free to ask questions! Email support@tenon.io with any questions you have along the way.

Post a Comment