ProgrammableWeb.com is the world's leading source of news and information about Internet-based application programming interfaces (APIs). Since it was founded in 2005, ProgrammableWeb has been chronicling the daily evolution of the global API economy while amassing the Web's most relied-on directory when it comes to discovering and searching for APIs to use in Web and mobile applications.
Between its editorial and directories, ProgrammableWeb is focused on providing content that will enable developers and business leaders alike to get the most out of their current or planned participation in the API economy. That content, developed by writers who are experts in their respective beats, comes in many forms--including reported news stories, analysis, reviews and how-to articles.
Over the years, in order to act on its mission of serving as the Web’s most comprehensive journal of the API economy, ProgrammableWeb has often relied on developers, API providers, and other practitioners to crowdsource its directories and contribute expert editorial content so that others can benefit from their knowledge. Contributed content is therefore another very important content type for ProgrammableWeb. We understand that many of the people most experienced with, and knowledgeable about, APIs are in the vendor community. Content conveying their thought leadership provides important perspective to the ProgrammableWeb community--as long as that content is developed in a way that focuses on technology and not on specific company, brand, or product agendas.
In other words, we welcome contributed content that is designed to inform our readers and help them do their jobs better. What we don’t want is a product, company, or brand pitch in disguise. The API economy is a level playing field, and we want to do our part to keep it that way. As such, we’ve created some guidelines to ensure fair play by all.
What’s in it for you?
The opportunity to build trust and demonstrate real thought leadership—two things that could go much further to promote your company and its products than any advertorial-equivalent ever could.
If you feel that you are up for the challenge, please take a look at (and follow!) the guidelines below. Please scroll to the bottom if you are here to list APIs, SDKs, libraries or other assets in one of our directories.
Three Types of Contributed Content
Generally speaking, ProgrammableWeb accepts four types of contributed content:
1. Contributed Articles
Contributed articles should focus on topics that are timely and relevant to the ProgrammableWeb community. The API landscape is changing by the day, so there is plenty of opportunity to help our community members understand and navigate it. For this reason, articles should be written by someone with technical “chops”—our readers want to see content from their peers, not from salespeople and marketing folks (no offense).
Contributed articles should:
- Provide thought leadership
- Be written with the ProgrammableWeb community’s needs and interests at top of mind
- Provide pragmatic value to the ProgrammableWeb audience (in other words, readers should be able to read your article and take some action on it).
Contributed articles should not:
- Promote your company's agenda, products, or services. For example, we will not accept submissions that are essentially written to stimulate interest or demand for solutions of the type that the author's employer sells. Additionally, we will not accept contributed articles that mention your company or products/services by name (except in the author's bio) with the exception of non-hyperbolic tutorials and how-to articles (see below)
- Appear, in whole, or in part, on any other websites, including your company's own website and/or blog
- Be written to drive click-throughs to another website, web page, branded content, etc. for the purposes of driving traffic (directly or through proxy content). We get a lot of submissions that, to us, are clearly written to drive traffic somewhere else. In some cases, the requirement of such a "back-link" is stated explicitly in the pitch. As soon as we see a link (or a requirement for one), our spider-senses start to tingle. If it's to a non-promotional resource of some sort (like a code sample, a third-party tool, etc.) that will come in handy to the reader, it's usually not a problem (as long as there's no registration wall). Keep in mind that when we publish your article, it will publish with a block of text at the bottom of the page that's "About the Writer." This profile can and should include a link to your employer's home page or to some other home page (eg: the writer's blog, a Github repo, etc.).
All contributed articles will include a disclaimer stating that the piece is contributed content and does not represent the opinions or reporting of the ProgrammableWeb editorial team.
Here are some articles that we consider contributed article exemplars.
- FBI Apple Debacle Is a Reminder of How Fingerprint Sensors Actually Worsen Security
- How REST APIs Are Driving the Digital Industrial Revolution
- How APIs Will Address the Challenges of Holland's Biggest IT Project Ever
2. How-To Articles and Tutorials
Companies can submit tutorials that take readers step-by-step through specific products or services. How-to’s can focus on a product that your company offers and/or on an industry-standard service. The most popular how-to’s are the most widely applicable. We will not publish tutorials that are focused on promoting a product rather than on supporting the ProgrammableWeb community in growing their knowledge about APIs and related technologies. Speaking to that point, submissions should be stripped of anything that would be deemed hyperbole. For example, "XYZ service is one of the leading providers of ABC functionality." Tutorials should be very matter of fact about getting something done.
If you’re not sure whether your how-to is educational or promotional, consider the following headlines:
OK: How To Set up an Automated API Security Test With Product X
Not OK: How to Use the Industry Leading Security Testing Tool to Automate API Security
Here are a couple of examples of contributed how-to articles that do well:
- How to Build an Events Database Using the ParseHub API, Python & Flask
- How to Create an Instagram Photo Printing App in Node.js
- How to Enable Web Apps for 2FA With the Nexmo Verify API
- How to Encrypt OAuth Tokens in 10 minutes With SecureDB
When and where tutorials depend on source code, it is imperative that the submission include that source code in a way that developers can easily copy and paste it from our site into their development environments. We use a special CSS style for source code. Source code should be broken into chunks in a way that makes it easy for the written narrative to explain what is going on in those chunks, leaving no stone unturned when it comes to educating the developer. You should assume that the developers reading your content will vary in levels of expertise with some being experts and others still familiarizing themselves with the fundamentals.
The Grandma Test
When writing a tutorial, we like to think in terms of "the Grandma Test." OK, so it's a bit of an exaggeration but the question is, if your grandmother was handed the tutorial and asked to make it all the way through to the end, could she? Or would she get stuck because an important detail was left out? We see it all the time. For example, you would be surprised at how many tutorials we receive that instruct the reader to enter a command without ever mentioning where exactly to enter the command or even the operating system that the reader should be working with. Also, you'd be amazed at the number of times we receive a tutorial that includes sample code that simply doesn't work. It's as if none of the various people involved with the submission actually took the time to try the step by step themselves.
So, that's why we call it the Grandma Test. If someone sat down with your tutorial having no preconceived notion of what to do or where to start, where would he or she get stuck in the step-by-step? Not sure? Give the tutorial to someone else -- someone that wasn't involved in producing it -- to try. Someone who isn't an expert in the subject matter.
We also know that you can't expect to hold everyone's hand through every tutorial. So, if there are prerequisites or assumptions involved -- for example, the tutorial assumes an intermediate level of working knowledge with Linux or OS X -- include a paragraph that details those assumptions in your tutorial.
Also, please note that ProgrammableWeb makes available a listing of code samples for developers who want to consume specific APIs. If you have a code sample you would like to list, scroll down to the section near the bottom of this document for information about working with ProgrammableWeb’s directories.
3. Press Releases
ProgrammableWeb publishes press releases that are focused squarely on topics relevant to our readership. There is no charge for publishing press releases. ProgrammableWeb will clearly label the content as a press release, and we reserve the right to edit the release for fit (such as headline length) and content (for example, to remove superfluous or irrelevant information). There is no guarantee that we will run submitted press releases, and, unfortunately, due to time constraints, we cannot respond to inquiries on a press release’s publishing status. We know: It sounds a bit like a roll of the dice, and it is. But please keep in mind that ProgrammableWeb’s editors do, in fact, read your press releases. Even if your release is not published, it is important to helping our team understand your news, your company, and your products and services. This, in turn, helps shape our editors’ long-term understanding of the API economy.
What To Expect
In an effort to ensure the best possible outcome for our readers, ProgrammableWeb’s editors are very engaged with all forms of contributed content. When working with the ProgrammableWeb team, here are a few things to expect:
- Since the rate of contributions tends to ebb and flow, we cannot guarantee a turnaround time on contributed articles. Generally speaking, all contributions go into a queue and are taken on a first-come, first-served basis. Depending on our current load, it can take us anywhere from a couple of days to a couple of weeks to start working on your contribution. We try to acknowledge receipt as soon as possible.
- Once we engage with you on a project, there will likley be several go-rounds between you and our editors before we are ready to publish your content. Some of this back and forth will involve questions we have--for example, when we need clarification on a certain point or when we think more information is necessary. In some cases we will let you know that we consider some or all of the content promotional, and will suggest and/or request changes. Please keep in mind that our editorial process is designed to provide our readers with the best possible experience, and that what makes us look good to our readers makes you look good too!
- Sometimes, we have to reject contributions. This happens on a fairly regular basis, mostly due to violation of these guidelines, irrelevance, lack of technical depth, or writing that requires too much attention from our editors just to make it legible. We look for uniqueness (relative to other content we've already published), authority and technical depth. If English is not the first language of the author, we strongly recommend that you have the submission reviewed and edited for legibility by someone who is fluent in English. If the contribution lacks these attributes and appears beyond repair--or if it is irrecoverably laced with hyperbole (yes, it happens all the time)--a raincheck may be in order. If a contribution violates these guidelines -- for example, if the content is delivered to us in the wrong format or if it appears to promote the agenda of the author's employer in some way -- the only response you will likely get is one that says your content was rejected on the basis of a guideline violation without further explanation.
- We do not offer reporting such as session counts, unique visitors, or pageviews on contributed content.
How to Submit Content
Still with us? Here’s how to submit content that adheres to the requirements we have provided above:
Submit an outline
The smoothest path to getting your content published on ProgrammableWeb is to submit an outline that pitches your proposed submission. This gives us the opportunity to gauge the viability of the content and to offer some guidance.
For contributed How-To’s and tutorials, it is best to submit a detailed outline. If your idea has merit, we may offer a couple of suggestions for ways to get it over the finish line.
You should send article outlines to firstname.lastname@example.org.
Outlines should include:
- The focus of your content
- The main take-away(s) for ProgrammableWeb readers (Ask yourself: What will the ProgrammableWeb reader get out of this? Why would he or she want to read this?)
- The name of the person who will be authoring the piece
- The credentials of the person who will be writing the piece (current title, brief bio, etc.)
- An acknowledgement that you have reviewed these guidelines. This saves time because that's always our first question. We do not read submissions until we're certain that these guidelines have been reviewed.
Sorry, but ambiguous proposals (like ones we get that say, “I am an experienced writer and would like to feature my content on your blog”) or proposals that list ideas that are completely irrelevant to ProgrammableWeb’s API-minded audience go directly to the trash bin wthout a reply. We appreciate the interest, but don’t have the resources to consider open-ended proposals. The more specific, the better.
How To Share Your Submission
If the article is already written (but not published elsewhere), you should share it with us as a viewable-by-anyone-who-has-the-link Google Doc. (Don’t worry--we won’t share the link with anyone). Later, if we accept your proposal, you will be asked to share the doc and provide edit access to ProgrammableWeb’s editors.
Regardless of where we are in the process of working with you, do not send a Word document. Always use Google Docs so our editors can immediately start collaborating on the content. We may invite other editors to help with the process. Please do not use any special formatting including boldface, italics, underlining or extranneous characters for emphasis like carats or asterisks. Contributions should be written in American English (this refers to the spellings of some words) and while it's fine to use acronyms after the first full usage of the phrase, your text should avoid shorthand and slang (ie: "org" instead of "organization"). Also, unless otherwise directed, do not submit content that involves introductions, footnotes or appendices. By introduction, we mean some sort of preamble that sets up the premise of the article and then says something like "with this in mind, John Smith will now tell you why blah blah blah." The author's name should not be mentioned anywhere within the article. It will be displayed in the byline, and at the bottom of the article where we'll include a short bio. Provide code samples in text format as opposed to screenshots.
Be sure to provide captions with any images, and link any references to off-site material or entities. If your tutorial involves any APIs, SDKs, libraries or frameworks, please make sure those assets have been added to our directories and that you link to those assets where appropriate. (See below for more information on adding assets to our directories.)
Many contributed tutorials get stuck in multiple rounds of editing because they omit important steps or lack sufficient detail. As a test of the thoroughness of any tutorials -- the ability to get the reader to the final objective without tripping-up -- find someone who is relatively inexperienced and see if, without any help, they can achieve that objective by following your tutorial. If they can’t, your tutorial is almost certain to get flagged for ambiguity and require more of our time and yours. The more thorough, the better and the faster the process will go!
Once we begin to collaborate on a document with you, please do not respond to our comments and edits by creating and sharing a new version of the document. It's imperative to a successful and efficient collaboration that we all continue to work on the original.
Registering Your Author’s Account with ProgrammableWeb
All articles that appear on ProgrammableWeb include the author’s byline and a short bio. These parts of the article are automatically displayed on the Web page by our technology. For any type of contributed content, content authors must create an account on ProgrammableWeb using this link: https://www.programmableweb.com/user/register.
Accounts must include a short user bio and at least one social ID. Think of the bio as your opportunity to convey why readers should be paying attention to what you have to say. The social ID is important because it offers readers a way to engage directly with the author. The best time to create this account is the point at which you submit your content to us. We’ve had to delay the publication of several articles because this step was neglected.
Submit a press release
To submit a press release, simply sent the document or a link to the document to email@example.com.
What About ProgrammableWeb’s Directories?
Many of ProgrammableWeb’s readers are developers who are using our directories to research APIs, SDKs and other resources for inclusion in their projects. Our directories are therefore an amazing way for API, SDK and library providers to improve the discoverability of their assets with developers.
As of the publishing of these guidelines, ProgrammableWeb offers four directories into which API and SDK providers, and other API technology providers, can load their assets:
The API Directory is our most popular directory. Here, developers can find thousands of APIs that are searchable by a variety of criteria, including category. While many of the APIs that are listed in the directory conform to the RESTful architectural style, REST is not a requirement. Our directory supports most networkable API architectural styles. To add an API to the API directory, go to /add/api/. Please be aware that all submissions go through a moderation process by our team before they are published. Depending on the length of our queue, this process can take anywhere from a couple of days to a couple of weeks. But no matter what, your submission will be acknowledged by an automated email almost immediately; an indication that your submission is now officially in our queue. In some cases, you may be contacted by a ProgrammableWeb staff member to clarify the information you provided.
Software development kits are very popular with developers interested in consuming an API. For the past few years, ProgrammableWeb has invested significant resources in developing a much more robust SDK directory. This directory includes SDKs from API providers, as well as independently produced SDKs from third parties and open source developers. Today, ProgrammableWeb’s SDK directory is a catch-all bucket for SDKs, libraries and frameworks. In our parlance, an SDK is a language/platform-specific kit for consuming an API. In contrast, we view libraries as platform-specific collections of source code that stand-up or provide APIs for a software product that’s not natively designed to do so. Frameworks are much larger, platform-enabling collections of library-like content. For example, ExpressJS.
In some future version of ProgrammableWeb, SDKs, libraries and frameworks will each get their own directory, and any data that you have already submitted will be appropriately migrated.
If you wish to register any of the three asset types, please use the following link:
Developers love code samples, and to support those developers, we also have a growing directory where you can register the location of sample source code for consuming your APIs or working with your SDKs. Of course, our preference is that you write a tutorial that’s replete with source code samples and publish that tutorial on ProgrammableWeb. But, this directory serves as a great fallback in the event that your code samples are already published somewhere else on the Web and you want ProgrammableWeb to point to them for you. To add a code sample, use the following link:
How We Connect The Dots
We appreciate the time you have taken to read these guidelines and the care you will take to follow them. We look forward to working with you!
Questions about making content submissions to ProgrammableWeb should be emailed to firstname.lastname@example.org