Mashery Getting Started Guide for Developers

Introduction

Mashery connects people who create APIs and Web Services (Service Providers) and the people who use them (you, a Developer). Each Service Provider has a Mashery-powered Portal including a Wiki, Documentation, and other content to support your implementation of their service. They also can use Mashery to power their APIs and Web Services, including API Key issuance, management, tracking and throttling.

How do I use Mashery?

It's easy. Just register with Mashery and sign up with the Service Provider. Your Mashery account will be linked with them until you delink it. If a Service Provider's Portal is public, you can view it without logging in. If a Service Provider's Portal is private, you will need to register with Mashery to access the Portal (you will still need to register for a public Portal as well if you want to add comments on the documentation, forums, and other content). You will also need a relationship with the Service Provider if you wish to use their APIs. Get the full scoop in registration docs.

What can I find in my Service Provider's Portals?

Each Portal provides content to support the services you are using: a wiki, documentation, custom pages, a forum, and a blog. Each one will be different, just like the Service Provider and their data. The type of content on the Portal may vary depending on how the Service Provider has configured its Portal. Expect to find documentation for using their tools, ask questions about usage and tools, and how you can use their APIs.

What can I do in the Portals?

To make happy Service Providers, Mashery is highly configurable. However, we do have a few set options and document types. Below you will find each of the content types available via Mashery so you can make sense of what kind of fun you can have. You must be registered to modify or add any content to a Portal. Look for information on a Service Provider's configuration in a viewable configuration file (coming soon).

Interactive content types such as the wiki and forum let you add posts and pages directly (if allowed), while documentation pages and the blog allow comments only. Custom pages are the only content type that do not allow any interactivity, and it is typically used for marketing, legal and other less-technology focused documents. Developers without moderation or administrator rights must use Markdown for all contributions. Markdown is a subset of HTML (similar to many wiki syntaxes) that will give providers less stress about exposing a wiki to the public. You will be able to style content and add links, but no scripting or attachments. Markdown is simple, but catchy.

  • Wiki: Recognize wiki pages by the /wiki/ in the path. If enabled by your provider, wiki is the place to create new and/or edit existing wiki pages. This is the section where you get to contribute the most. It is perfect for developer-maintained application galleries, how-to's, articles and sample code libraries. With the huge problem of spam, be advised that some providers might want to approve your change first, so you might see a delay while administrators/moderators review it. Here's how to use these pages:

    • Create a wiki page by clicking Create New Wiki Entry viewable when you are logged in, or by accessing the following URL (preceded by your Service Provider's address): http://yourproviders.masherysite.com/index.php/wiki/add/newPage. Markdown only.
    • Edit a wiki page by clicking Edit This Page viewable when you are logged in, or by accessing the following URL (preceded by your Service Provider's address): http://yourproviders.masherysite.com/index.php/wiki/edit/path. Markdown only.
    • Add a comment or annotation to the wiki page by clicking Add Comment viewable when you are logged in. Markdown only.
  • Docs: Recognize docs pages by the /docs/ in the path. Docs pages are the place to feature documentation because they support full HTML (as well as Markdown) and allow developers to comment directly on the page, appearing at the bottom. Developers like you can add your tips and tricks on the same page as the developers of the Web Services. Be advised that some providers might want to approve your comments first, so you might see a delay while administrators/moderators review. Here's how to use these pages:

    • Add a comment or annotation to the docs page by clicking Add Comment viewable when you are logged in. Markdown only.
  • Blog: Recognize blog posts by the /blog/ in the path. The Blog is where your Service Provider will share news items, commentary or announcements. You can leave comments, which then appear at the bottom. Be advised that some providers might want to approve your comments first, so you might see a delay while administrators/moderators review. Here's how to use this area:

    • Add a comment or annotation to the blog post by clicking Add Comment viewable when you are logged in. Markdown only.
  • Forum: Recognize forum posts by the /forum/ in the path. Forum posts are for threaded discussions of features, implementation details, troubleshooting and questions. This is your area - developers can respond to existing threads or start new ones. Be advised that some providers might want to approve your comments first, so you might see a delay while administrators/moderators review. Here's how to use this area:

    • Start a forum topic by clicking Start a New Topic viewable when you are logged in. Markdown only.
    • Add a responding forum post by clicking Add Comment viewable while you are reading each forum post when you are logged in. Markdown only.

What's this going to cost me?

For our Beta period, it's all free! But after the Beta period, Service Providers may change their terms of use and start charging. Getting stuff for free is great, but we all have to eat. Plus, paying for services will give you greater access to cool data. After the Beta period, check with the Service Provider whose services you're using for information on charging. Heck, even if they start charging, try to talk them into an exception - if you add enough value to their product, maybe they can even pay you!!

For more information: