This is a tutorial on how to add your API(s) to Mashape. Do note that things change quite often so if you’re reading this from the future, some things might have changed. But we’ll update this as often as we can so everyone’s on the same page (literally!).
Before we start, you would need a Mashape account. (You can skip this part if you’ve done this already). Go to http://www.mashape.com/ and click on the button in the upper-right hand section of the page that says “Join Us”. You’ll also have the option to sign up using your GitHub account.
After signing up, you’ll get a verification email. Just open that email and click on the verification link. You will then be taken back to your Dashboard. Your Dashboard is your “private control panel” where you view and control all aspects of the APIs you create and consume.
For now, we’re just interested in adding an API.
1. Add an API
Go ahead and click Add an API in your Dashboard. You will then be presented with a simple form asking you for two things – an API name and a base final URL.
(For this, let’s just imagine that we “own” the Eventbrite API).
As such, we’ll put in “Eventbrite” and the base URL as “https://www.eventbrite.com/json/”. Then go ahead and click “Add API”.
2. Describe the API
You will then be taken to the API page, to fill it in with information to fully “describe” your API. You can start anywhere from picking a logo for your API, a category, a text description, and so on. For now, we’ve chosen to lay out my API endpoints. To do that, we click “Create Documentation.”
Note: A “Documentation” in this context is much more than a simple readme file for your API endpoints. But equally simple, as you will see next.
The Documentation page is where you fully describe your API endpoints. Let’s break this whole page down one by one. The left navigation pane are actually tabs that drive large pane on the right. From here you can add Authentication settings (if your API requires it), add your Endpoints, and add Models. Models are simply response “Models” that describe the output of a particular endpoint.
As you can see on the dropdown above, several Authentication settings are supported. This will grow over time so be sure to check back once in a while, or email us at email@example.com if you have suggestions/recommendations.
The Endpoints section is where you define the connection points of your API service, typically represented by an HTTP url string. The information you put here are the most basic information that a developer will usually need to call your API endpoint. These include:
- HTTP Method (GET, POST, PUT, DELETE)
- HTTP Route – you can specify parameters here
- Parameter format – Form or JSON
- Parameters list – You can control whether a parameter is optional or required, etc.
- Response – You can build the Response Model here
You can keep adding Endpoints and Models as required by your API.
Here’s an example of the Endpoints section filled in with the Eventbrite event_search definition.
Once the information has been filled (we can skip the Model part for now), we can go ahead and test if Mashape can connect to your API. That’s what the “Generate Response” button is for.
3. Test the API
The “Generate Response” button allows you to check if you can establish a connection with your API endpoints, as a developer would, if he/she were consuming your API in bare bones fashion. This will check whether you provided the correct authentication, HTTP route, parameters, among other things. This minimal work of testing the endpoint goes a long way in making sure developers are consuming your API endpoints the right way.
Note though, that instead of calling the button “Test Endpoint” (which will come later by the way), it is named “Generate Endpoint” because that’s what we’re doing at this point – generating a Response example that will be captured for the Model section.
Here’s what it looks like after I have successfully generated a response – a Model and “example” response was generated:
At this point, we can start filling in the Fields section with the response “fields” text descriptions. You probably have this field description text somewhere already, so you just need to put them here. Although the endpoint will still be accessible to developers without this field information and description, it is advisable to put them here so that it will complement the response information with field descriptions, and make it easier for developers to understand what they’re getting back from your endpoint. You can also associate these responses with different Models. Just add new Models from the left panel.
That’s it for one endpoint. If you have several endpoints, you just have to repeat Step 3 for all of them. But it’s usually better to “save” one endpoint first before you move ahead with another. So let’s do that now.
4. Save the Documentation
The “Save Documentation” button at the lower-right hand corner of the Documentation panel will save the work that you have done so far. It will also catch if you have some errors in the Response (e.g. malformed responses, etc). You can click on that now.
After you have successfully saved your API documentation, note that you have not yet provided a general (lengthier) text description for your API, website, logo, and no category was set. These details are important so that developers will find your API, and see that you actually mean business!
To fill in this information, go up and click the “Settings” tab. Here’s an example:
Once done, click the “Save Settings” button at the bottom.
5. Make your API public in the Marketplace!
Note that your Endpoint is still in “private” mode, which means that if you intended for this API to be consumed publicly, you have to turn it on for “public” use. For this API, we intend to make it public, so let’s go ahead and do that. Go look for the toggle in the upper-right hand corner that looks like this:
Click on it to make your API public. It should turn green like this:
Once it’s public, developers can start searching for it in Mashape and consume it! Congrats!
Along the way, you might have noticed a few other features of Mashape such as billing and permission add-ons, custom DNS subdomain, Github login, embeddable docs, etc. We’ll explore these features in a separate blog post in more detail in the near future. But feel free to test them out and play with them. And most importantly, tell us about your experience!
Here at Mashape, we want to create the best API Cloud Marketplace for all types of developers. And we can only do that with your feedback and support. You can email us at firstname.lastname@example.org or party with other Mashapers in our Facebook page.