Support/Kitsune/SUMO API

This is the project page for creating the SUMO API for Kitsune.

Vision statement

SUMO contains hundreds of articles, localized in several languages. At the moment, the only way to consume this content is by visiting support.mozilla.com. By implementing an API we want to provide internal and external web developers a simple plug-and-play method of displaying SUMO content (links, articles, snippets, etc) in their site.

Goals

• Increase Support Visibility
• Reduce duplication of efforts

Concerns

• Overload the SUMO traffic.

Use Cases

Product Page

Article Snippets (similar example: http://www.mozilla.com/en-US/firefox/security/)

• A new product is going to be launched and a site is created
• SUMO content is created for the product.
• Engagement wants to include some FAQs in the new site.
• To ensure that the content is up to date the Title for the link and the search summary is pulled from the SUMO FAQs, calling for an specific article.
• The content is then formatted with the CSS of the page.

Article Content (example: http://www.mozilla.com/en-US/mobile/sync/)

• In the same product page, engagement decides to explain how to configure the new feature.
• They decide to include the steps in a template stored at SUMO.
• Instead of hardcoding the steps, they include a call to the API to fetch an specific article that is always updated.
• The content will be customized based on the user reading it (i.e. user agent) and the page's CSS.
  • We will probably need to insert our own CSS/JS, for things like /buttons/ or to hide showfor content.

Top Articles

• The team working on BrowserID wants to include a page for Users explaining what it is.
• SUMO has content explaining how to use it and how to troubleshoot it.
• BrowserID team decides to include a widget with the most popular topics.
• They embed a query to the SUMO database that presents a configurable (amount of items, tags) list of the top articles relevant to the product.
  • What happens when people click on the links? Are thy sent to SUMO?
• The list can be formatted with the CSS to match the look and feel of the site.

Auto Customization - NOT PRIORITIZED

• The AMO team has created a dashboard where you can see all the add ons that you have downloaded.
• They want to include a list of relevant SUMO articles.
• To fetch the list they use the SUMO API and they include the codenames of the add-ons as part of the query.
• Based on this additional parameters (signals), the API will provide the most relevant articles based on a previous manual configuration.

Contributors with their Own site

Contributor Widget - NOT PRIORITIZED

• David is a contributor
• He wants to show on his site a set of articles where he has contributed.
• He uses the code snippets that SUMO provides and paste it on his site.
• The widget allows David to configure:
  • View by Most Recent or More Visited.
  • Filter by keyword.
• The widget also shows the Karma level of this user.

Not sure this is really necessary. It would add nothing for anyone beyond David. -Kadir

Search box redirecting to SUMO

• David is a big fan of providing Firefox support.
• Because of it, he wants to make sure that anyone visiting his site can find answers to their Firefox questions.
• The search box in his site allows users to search in SUMO the same way as if they were at support.mozilla.com
• For David, including this search box is a simple as including a code snippet in his site.
• The search results would be displayed in SUMO.

Search box returning article list

• James is a big fan of providing Firefox support and he is an avid developer.
• He wants to help users but he also wants to keep the traffic on his site.
• The search box in his site allows users to search in SUMO the same way as if they were at support.mozilla.com
• For James, including this search box is a simple as including a code snippet in his site.
• The search query will return a list of article links matching the search criteria.
• James can customize a landing page so the results are displaying with the same look and feel as his site.

Local Mozilla communities

Mozilla Hispano wants to render the spanish content in SUMO in their own site, but instead of replicating SUMO or sending traffic to SUMO they want to present it in combination with their own content.

Features

P0 - Critical

This is the basic collection of features the service need to have in order to officially go live.

• The API should return the article content in text format.

• It should offer the following features:
  • Content
    • A webmaster can fetch the whole SUMO article querying the API with the Title of the article.
  • For:
    • Possibility to Retrieve a specific {for}.
    • Capability to offer dynamic content that gets customized based on the User Agent.
  • Style:
    • Offer predefined CSS (this can be done as a file attached to the documentation).
    • Possibility to customize the presentation with a custom CSS.

• The API needs to be documented.

P1 - Important

The following list of features should be the ones that follow the initial launch and should be ready in 2 quarters after the official launch of the service.

• There needs to be a counter of each article.
• There needs to be a list of pages using it with a counter of queries per week.
• There needs to be a possibility to block pages from using it.

P2 - Nice To Have

The platform would benefit from these features but they are not required for the daily usage of it.

• A webmaster can fetch a section of a SUMO article querying the API with the Title of the article and the name of the anchor.

Unprioritized features

Features that we may want to implement in a future, or we want to think about in a second stage

Other Documents