Thinking of opening an API, or acknowledging that you have already done so by shipping a Web site? Here's a README you can use, which is full of sneaky best-practice advice for both you and your developers.
Greetings, brave pilgrim! We're delighted to hear that you're building a project around OurThing. Here's what you need to know before going any further.
OurThing is a valuable resource for millions of people and businesses, and we will do whatever we need to do in order to keep it that way. As long as what you're building adds value for the entire OurThing community--including us, its proprietors--everything will work out fine.
What follows is an incomplete set of guidelines for building on OurThing, which will be refined and expanded in the future.
Do not pretend to be OurThing. Contribution to OurThing is a directed experience, one which we intend to control. This is not negotiable. Therefore:
- Do not attempt to build an OurThing client, or a significant subset of a OurThing client, even if none presently exists for a device, browser, or operating system that you genuinely love and want to support.
- Do not pretend that your application is “sponsored by” or “in partnership with” OurThing. It's not.
- Do not confuse OurThing customers about the difference between your project and OurThing. Follow brand guidelines in the naming, design, and marketing of your application or service.
- Do not pretend to be an OurThing customer. Do not ask for, collect, store, or use an OurThing customer's browser cookie, login credentials, or API client identifiers, even if you believe that our customer has granted you permission to do so.
- Do not pretend to be the OurThing API. Do not store or redistribute any data you harvest from us.
- Do not copy and redistribute assets (such as fonts, scripts, images, sounds, or videos) from OurThing for any reason. All assets sent to users of your application must come directly from the OurThing content distribution network, which has been specifically engineered to stand up under the load.
Do not alter our design. If you're displaying content from OurThing, display it per our specifications, without changing or omitting anything. Do not present anything from OurThing without crediting us with a link.
From time to time, OurThing may display a resource that was originally hosted on another online service. When this happens you'll know it, because you'll see attribution to the original source. Do not alter or omit original source attribution.
If you sell something that uses an unsupported API and we change it, your customers will see broken results and it will be viewed by them as our fault. This is fundamentally unfair to everyone, especially us, and subtracts a huge amount of value from OurThing.
- Screen- and API-scraping is an unsupported API. Do not scrape. If we're not supplying it via a supported API, you don't get to build on it. If we catch you scraping, we will take steps to shut you down.
- We're aware that several applications have already been built on unsupported APIs. We will do our best to notify you in advance of changes or shutdowns--please see Keep In Touch, below--but we can't guarantee anything.
- Several of our endpoints are wide open because they are called directly from the browser with JavaScript. Please feel free to use these to build client-based experiments that use OurThing to delight visitors to your site. As long as all requests go directly from the client browser to OurThing's API and back, and you follow all the rules listed above--especially the one about not selling anything built on an unsupported API--everything will be cool.
- Do not abuse our open endpoints. If you're hitting CoolStufCounter millions of times per day in a misguided attempt to build real-time analytics, you are subtracting value from OurThing and we will take steps to shut you down.
We've recently added the ability to sign in to OurThing with your HitGub account, and to add your HitGub account to your OurThing user profile as a social media profile. Please do this if you're building on our work; we will be using HitGub as our only means of contact with the developer community.
All OurThing developer communication will occur via HitGub, via Issues and the Wiki. We suggest you watch our main repository of documentation at least, and narrow it down to specific areas if the noise--it's presently very quiet--gets to be too loud.
To see what HitGub interactions look like, please visit our repository, here:
https://hitgub.com/OurThing/CoolStuf
The CoolStuf widget, which is featured on millions of sites all over the Web, went up on HitGub several years ago; you can see that we've already had bugs and feature requests asked and answered, and have even merged a few pull requests. (If you're looking to work for OurThing, contributing code is a really great way to let us know!)
API documentation will continue to appear on HitGub as well; just south of here on the CoolStuf wiki is where you can read up on our open JavaScript endpoints, mentioned above.
Finally, this document will always be found in the root directory of our HitGub repository as README.MD. It may change from time to time, but we'll leave its history alone, so you'll always be able to see what happened and when.
Have fun, and please let us know what works and what doesn't.
--Team OurThing