Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OTWO-7320 Update ohloh api docs #38

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Copyright (c) 2013 Black Duck Software, Inc. and its contributors.
Copyright (c) 2025 Black Duck Software, Inc. and its contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
42 changes: 21 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Ohloh API Documentation
# Open Hub API Documentation

## Welcome

The Ohloh API is a free, REST-based programming interface to the Black Duck Open Hub open source directory. You can use the Ohloh API to create your own applications and web services based on Open Hub data.
The Open Hub API is a free, REST-based programming interface to the Black Duck Open Hub open source directory. You can use the Open Hub API to create your own applications and web services based on Open Hub data.

## Getting Help

This page contains important summary information to help you get started. In-depth online documentation is available, linked by the table of contents below.

Some sample code can be found on the [Examples](examples/) page. For questions not covered in the documenation, the [Open Hub Technical Issues Help](https://community.synopsys.com/s/topic/0TO2H000000gHS1WAM/black-duck-open-hub-help) can provide additional help.
Some sample code can be found on the [Examples](examples/) page. For questions not covered in the documenation, the [Open Hub Technical Issues Help](https://community.blackduck.com/s/topic/0TO2H000000gHS1WAM/black-duck-open-hub-help) can provide additional help.

Send bug reports to [email protected].

## Table of Contents
+ [Lookup By Email](email_lookup.md)
+ [Using OAuth with the Ohloh API](examples/oauth2)
+ [Using OAuth with the Open Hub API](examples/oauth2)
+ [Examples](examples/)
+ Ohloh API Reference
+ Open Hub API Reference
- [Account](reference/account.md)
- [Account News](reference/news.md)
- [ActivityFact](reference/activity_fact.md)
Expand Down Expand Up @@ -47,7 +47,7 @@ Send bug reports to [email protected].

## Terms of Use

The Ohloh API has some restrictions. Please review the complete [Terms of Use](https://community.synopsys.com/s/article/Black-Duck-Open-Hub-API-Use-Agreement) before you begin.
The Open Hub API has some restrictions. Please review the complete [Terms of Use](https://community.blackduck.com/s/article/Black-Duck-Open-Hub-API-Use-Agreement) before you begin.

We ask that you cite Open Hub in publications that use our data. Please include a link to https://www.openhub.net on your web pages.

Expand All @@ -61,9 +61,9 @@ We recommend linking to our home page. The following html will link the small ba

## API Key

Before you can access the Ohloh API, you must [register your application](https://www.openhub.net/accounts/me/api_keys/new) and obtain an API key. Bandwidth will initially be limited to 1,000 requests per API key per day.
Before you can access the Open Hub API, you must [register your application](https://www.openhub.net/accounts/me/api_keys/new) and obtain an API key. Bandwidth will initially be limited to 1,000 requests per API key per day.

An API Key should be unique to each application that accesses the Ohloh API. You can register up to five applications.
An API Key should be unique to each application that accesses the Open Hub API. You can register up to five applications.

It is important not to share API keys. In order to access or modify account data, your application must be granted permission by an individual Open Hub account holder. This permission is granted on a per-key basis.

Expand All @@ -73,32 +73,32 @@ If you have special requirements for additional keys, or if you are interested i

## OAuth Impersonation

The standard Ohloh API allows read-only access to Open Hub data.
The standard Open Hub API allows read-only access to Open Hub data.

Using OAuth, you can impersonate an Open Hub account while accessing the Ohloh API. This enables you to write to the Open Hub database, and also to access or modify private account information. You must first be granted permission to do this by an Open Hub account holder.
Using OAuth, you can impersonate an Open Hub account while accessing the Open Hub API. This enables you to write to the Open Hub database, and also to access or modify private account information. You must first be granted permission to do this by an Open Hub account holder.

You can read more at [Using OAuth with the Ohloh API](examples/oauth2#using-oauth-20).
You can read more at [Using OAuth with the Open Hub API](examples/oauth2#using-oauth-20).

## Forming a Request

The Ohloh API returns XML-formatted data in response to HTTP GET requests.
The Open Hub API returns XML-formatted data in response to HTTP GET requests.

The design concept is that for each web page on Open Hub, there may be an equivalent XML-formatted version of the page. Most pages on the Black Duck Open Hub have an XML representation.

You must do three things to receive an XML-formatted response:

1. Append a `.xml` extension to the basic URL. For example, instead of `https://www.openhub.net/projects/1`, which returns an HTML page, you would request `https://www.openhub.net/projects/1.xml`.
1. Append a `.xml` extension to the basic URL. For example, instead of `https://www.openhub.net/p/1`, which returns an HTML page, you would request `https://www.openhub.net/p/1.xml`.
2. Provide your API Key as an HTTP parameter. Your request will be forbidden without a valid `api_key`.

For example, to view the project with ID=1 as XML, using an example API key, the complete URL would be:

```
https://www.openhub.net/projects/1.xml?api_key=01234567890123456789
https://www.openhub.net/p/1.xml?api_key=01234567890123456789
```

For the sake of brevity, the `api_key` parameter will be omitted from the examples in this documentation. Remember to always include it in your actual queries.

Note that the Ohloh API previously required the use of a version parameter `v`. This is no longer required, and will be ignored.
Note that the Open Hub API previously required the use of a version parameter `v`. This is no longer required, and will be ignored.

## XML Response Format

Expand Down Expand Up @@ -137,7 +137,7 @@ A sample response to a project request might be:
</response>
```

All XML returned from the Ohloh API will be contained within a root element called `<response>`, which will always contain a `<status>` element.
All XML returned from the Open Hub API will be contained within a root element called `<response>`, which will always contain a `<status>` element.

The `<status>` element will contain either `success` or `failed`.

Expand All @@ -153,20 +153,20 @@ If the `status` is `failed`, then the HTTP response code will be set appropriate
</response>
```

Details about this project response can be found in the Ohloh API Reference [project page](reference/project.md).
Details about this project response can be found in the Open Hub API Reference [project page](reference/project.md).

## Collection Requests

### Collection Request Parameters

+ __query__ - Results will be filtered by the provided string. Only items that contain the query string in their names or descriptions will be returned. Filtering is case insenstive. Only alphanumeric characters are accepted. All non-alphanumeric characters will be replaced by spaces. Filtering is not available on all API methods, and the searched text depends on the type of object requested. Check the reference documentation for specifics.
+ __sort__ - Controls the sort order of the returned results. Typical supported values are name, created_at, and updated_at. The specific sort options available depend on the type of object requested, so check to the reference documentation for specifics. _API does not support reverse sorting_.
+ __page__ - In most cases, the Ohloh API returns at most 25 items per request. Pass this parameter to request subsequent items beyond the first page. This parameter is _one-based_, with a default value of 1. If you pass a value outside the range of available pages, you will receive the first page.
+ __page__ - In most cases, the Open Hub API returns at most 25 items per request. Pass this parameter to request subsequent items beyond the first page. This parameter is _one-based_, with a default value of 1. If you pass a value outside the range of available pages, you will receive the first page.

For example, to get the second page of projects containing “java” or “Java” in their titles, descriptions, or tags, you would request:

```
GET https://www.openhub.net/projects.xml?query=java&page=2
GET https://www.openhub.net/p.xml?query=java&page=2
```

### Collection Response XML Format
Expand All @@ -177,7 +177,7 @@ Some results will contain a collection of values. When this happens, the `<respo
+ __items_available__ - The total number of database items matching the query, including those already returned.
+ __first_item_position__ - The zero-based index of the first item returned

For example, the response to `https://www.openhub.net/projects.xml` might begin:
For example, the response to `https://www.openhub.net/p.xml` might begin:

```xml
<response>
Expand All @@ -193,4 +193,4 @@ For example, the response to `https://www.openhub.net/projects.xml` might begin:
```

- - -
Copyright 202 Synopsys, Inc. Unless otherwise marked, this work is licensed under a [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).
Copyright 2025 Black Duck Software, Inc. Unless otherwise marked, this work is licensed under a [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).
6 changes: 3 additions & 3 deletions email_lookup.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
## Lookup By Email

The Ohloh API allows you to retrieve an [Account](reference/account.md) using the MD5 hash of the account’s email address.
The Open Hub API allows you to retrieve an [Account](reference/account.md) using the MD5 hash of the account’s email address.

You can pass the MD5 hash of an email address in any URL that normally expects an Account ID.

This is useful if you know someone’s email address, but do not know the Ohloh account ID. This might be the case if you are hosting a web site with registered users who have supplied their email addresses. With the Ohloh API, you can easily find Ohloh statistics about your registered users.
This is useful if you know someone’s email address, but do not know the Open Hub account ID. This might be the case if you are hosting a web site with registered users who have supplied their email addresses. With the Open Hub API, you can easily find Open Hub statistics about your registered users.

For example, here’s how to find the account data for `[email protected]`:
+ Generate the MD5 hash for `[email protected]`. From a irb shell you can do this simply:
Expand All @@ -19,4 +19,4 @@ f1c4c8746d8e42872f6db32977ad5d61
$ curl https://www.openhub.net/accounts/f1c4c8746d8e42872f6db32977ad5d61.xml?api_key=<YOUR API KEY>
```

Ohloh does not publish email addresses. You must already know the email address of the account you are looking for. Because the search is done using the MD5 hash of the email address, the email address comparison is case sensitive and must match exactly.
Open Hub does not publish email addresses. You must already know the email address of the account you are looking for. Because the search is done using the MD5 hash of the email address, the email address comparison is case sensitive and must match exactly.
2 changes: 1 addition & 1 deletion examples/ApiExample.cpp/build/vs2005/OhlohApiExample.sln
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

Microsoft Visual Studio Solution File, Format Version 9.00
# Visual Studio 2005
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "OhlohApiExample", "OhlohApiExample.vcproj", "{EA66C001-B006-4DBA-9542-A5E887BA420C}"
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "OpenHubApiExample", "OpenHubApiExample.vcproj", "{EA66C001-B006-4DBA-9542-A5E887BA420C}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Expand Down
4 changes: 2 additions & 2 deletions examples/ApiExample.cpp/build/vs2005/OhlohApiExample.vcproj
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
<VisualStudioProject
ProjectType="Visual C++"
Version="8,00"
Name="OhlohApiExample"
Name="OpenHubApiExample"
ProjectGUID="{EA66C001-B006-4DBA-9542-A5E887BA420C}"
RootNamespace="OhlohApiExample"
RootNamespace="OpenHubApiExample"
Keyword="Win32Proj"
>
<Platforms>
Expand Down
2 changes: 1 addition & 1 deletion examples/ApiExample.cpp/temp.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<account>
<id>114148</id>
<name>Jim Berets</name>
<about>VP, Product Management, Black Duck. I'm responsible for openhub.net as well as Black Duck's enterprise products. If you have any questions, comments, or concerns regarding Ohloh, please post them on our forum or email us at [email protected].</about>
<about>VP, Product Management, Black Duck. I'm responsible for openhub.net as well as Black Duck's enterprise products. If you have any questions, comments, or concerns regarding Open Hub, please post them on our forum or email us at [email protected].</about>
<login>jberets</login>
<created_at>2010-10-06T16:15:18Z</created_at>
<updated_at>2013-07-10T19:20:03Z</updated_at>
Expand Down
12 changes: 6 additions & 6 deletions examples/ApiExample.java
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,16 @@ of this software and associated documentation files (the "Software"), to deal
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

This is an example of using the Ohloh API from Java.
Detailed information can be found at the Ohloh website:
This is an example of using the Open Hub API from Java.
Detailed information can be found at the Open Hub website:

https://github.com/blackducksw/ohloh_api
https://github.com/blackducksoftware/ohloh_api

This examples retrieves a account and simply shows the name associated.

Pass your Ohloh API key as the first parameter to this example.
Ohloh API keys are free. If you do not have one, you can obtain one
at the Ohloh website:
Pass your Open Hub API key as the first parameter to this example.
Open Hub API keys are free. If you do not have one, you can obtain one
at the Open Hub website:

https://www.openhub.net/accounts/<your_login>/api_keys/new

Expand Down
18 changes: 9 additions & 9 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
## Ohloh API Examples #
Some basic [Ohloh](https://www.openhub.net) API samples to help you get started. For information on the Ohloh API, please see the [documentation](/README.md). The Ohloh API has some restrictions, so please review the complete [Terms of Use](http://blog.openhub.net/terms-2) before you begin.
## Open Hub API Examples #
Some basic [Open Hub](https://www.openhub.net) API samples to help you get started. For information on the Open Hub API, please see the [documentation](/README.md). The Open Hub API has some restrictions, so please review the complete [Terms of Use](http://blog.openhub.net/terms-2) before you begin.

### Examples are available in: ###
* BASH

Uses `curl` to pull an [Account](/reference/account.md) from Ohloh and `openssl` to create MD5 hex of the email address. A simple sed hack parses the XML response into name:value pairs. The example demonstrates data retrieval using email address lookup. Pass your API key and the email address of the Account you are requsting as parameters to the script:
Uses `curl` to pull an [Account](/reference/account.md) from Open Hub and `openssl` to create MD5 hex of the email address. A simple sed hack parses the XML response into name:value pairs. The example demonstrates data retrieval using email address lookup. Pass your API key and the email address of the Account you are requsting as parameters to the script:

`./account_sample.sh YOUR_API_KEY_HERE [email protected]`

The script isn’t very robust — `sed` is not the world’s best XML parser — but it does return a non-zero exit code if the record is not found or some other problem occurs.

* Ruby

Performs the same email-based account lookup, but uses more rigorous error handling and parsing to create a structured XML document object. Using the `REXML` library, you can build a more robust interface to the Ohloh API.
Performs the same email-based account lookup, but uses more rigorous error handling and parsing to create a structured XML document object. Using the `REXML` library, you can build a more robust interface to the Open Hub API.

Execute the script by passing your API key and an email address as parameters:

`ruby account_sample.rb YOUR_API_KEY_HERE [email protected]`

* Python

Performs a similar account lookup on Ohloh. It requires `urllib`, `hashlib` and `elementtree`.
Performs a similar account lookup on Open Hub. It requires `urllib`, `hashlib` and `elementtree`.

Execute the script by passing your API key and an email address as parameters:

Expand All @@ -30,7 +30,7 @@ Some basic [Ohloh](https://www.openhub.net) API samples to help you get started.

* Perl

Performs a similar account lookup on Ohloh. It requires the `LWP::Simple`, `Digest::MD5`, and `XML::Simple` libraries.
Performs a similar account lookup on Open Hub. It requires the `LWP::Simple`, `Digest::MD5`, and `XML::Simple` libraries.

Execute the script by passing your API key and an email address as parameters:

Expand All @@ -40,7 +40,7 @@ Some basic [Ohloh](https://www.openhub.net) API samples to help you get started.

* Java

Uses Java’s networking capabilities to pull an [Account](/reference/account.md) from Ohloh. It demonstrates how to generate an MD5 hash of an email address to use as a lookup key, then uses DOM to parse the XML response.
Uses Java’s networking capabilities to pull an [Account](/reference/account.md) from Open Hub. It demonstrates how to generate an MD5 hash of an email address to use as a lookup key, then uses DOM to parse the XML response.

Pass your API key and the email address of the Account you are requesting as parameters:

Expand All @@ -55,7 +55,7 @@ Some basic [Ohloh](https://www.openhub.net) API samples to help you get started.
The code was written for Visual Studio 2005, but it also compiles and runs on Mac OS X, and should work on Linux. Let us know if you encounter trouble on your platform.

To build with Visual Studio 2005:
* Open solution file `ApiExample.cpp/build/vs2005/OhlohApiExample.sln`
* Open solution file `ApiExample.cpp/build/vs2005/ohlohExample.sln`
* Right-click the solution and choose *Build*.

To build on Linux or Mac OS X, *cd to ApiExample.cpp* and run the build script:
Expand All @@ -70,7 +70,7 @@ Some basic [Ohloh](https://www.openhub.net) API samples to help you get started.

* PHP

Paul Scott has created a full-featured PHP class for accessing the Ohloh API, complete with documentation. You can find it at the [PHP Classes](http://www.phpclasses.org/browse/package/4261.html) website.
Paul Scott has created a full-featured PHP class for accessing the Open Hub API, complete with documentation. You can find it at the [PHP Classes](http://www.phpclasses.org/browse/package/4261.html) website.


Your feedback on these examples will benefit everyone, and we’re eager for input on improvements.
Expand Down
Loading