From 464f70fc6eab9c3758998bbaa6ec65bbec926e95 Mon Sep 17 00:00:00 2001 From: Priya Rani Date: Wed, 15 Jan 2025 18:42:05 +0530 Subject: [PATCH 1/2] OTWO-7320 Update ohloh api docs --- README.md | 42 ++++++++--------- email_lookup.md | 6 +-- .../build/vs2005/OhlohApiExample.sln | 2 +- .../build/vs2005/OhlohApiExample.vcproj | 4 +- examples/ApiExample.cpp/temp.xml | 2 +- examples/ApiExample.java | 10 ++-- examples/README.md | 18 +++---- examples/account_sample.pl | 12 ++--- examples/account_sample.py | 16 +++---- examples/account_sample.rb | 16 +++---- examples/account_sample.sh | 16 +++---- examples/oauth2/README.md | 10 ++-- examples/oauth2/ohloh_oauth2_sinatra.rb | 4 +- reference/account.md | 26 +++++----- reference/activity_fact.md | 8 ++-- reference/analysis.md | 18 +++---- reference/code_location.md | 43 +++++++++++++++++ reference/contributor_fact.md | 16 +++---- reference/contributor_language_fact.md | 6 +-- reference/enlistment.md | 12 ++--- reference/factoid.md | 16 ++----- reference/kudo.md | 8 ++-- reference/kudo_score.md | 6 +-- reference/language.md | 22 ++++----- reference/message.md | 4 -- reference/news.md | 4 -- reference/organization-collection.md | 4 +- reference/organization.md | 4 +- reference/position.md | 8 ++-- reference/project.md | 47 +++++++++++++------ reference/repository.md | 45 ------------------ reference/size_fact.md | 8 ++-- reference/stack.md | 19 ++------ 33 files changed, 230 insertions(+), 252 deletions(-) create mode 100644 reference/code_location.md delete mode 100644 reference/message.md delete mode 100644 reference/news.md delete mode 100644 reference/repository.md diff --git a/README.md b/README.md index d63a80c..4b72e0f 100644 --- a/README.md +++ b/README.md @@ -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 info@openhub.net. ## 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) @@ -47,7 +47,7 @@ Send bug reports to info@openhub.net. ## 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. @@ -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. @@ -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 @@ -137,7 +137,7 @@ A sample response to a project request might be: ``` -All XML returned from the Ohloh API will be contained within a root element called ``, which will always contain a `` element. +All XML returned from the Open Hub API will be contained within a root element called ``, which will always contain a `` element. The `` element will contain either `success` or `failed`. @@ -153,7 +153,7 @@ If the `status` is `failed`, then the HTTP response code will be set appropriate ``` -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 @@ -161,12 +161,12 @@ Details about this project response can be found in the Ohloh API Reference [pro + __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 @@ -177,7 +177,7 @@ Some results will contain a collection of values. When this happens, the ` @@ -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/). diff --git a/email_lookup.md b/email_lookup.md index c1c9c83..78a4032 100644 --- a/email_lookup.md +++ b/email_lookup.md @@ -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 `info@openhub.net`: + Generate the MD5 hash for `info@openhub.net`. From a irb shell you can do this simply: @@ -19,4 +19,4 @@ f1c4c8746d8e42872f6db32977ad5d61 $ curl https://www.openhub.net/accounts/f1c4c8746d8e42872f6db32977ad5d61.xml?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. diff --git a/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.sln b/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.sln index 55fe131..b31677c 100644 --- a/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.sln +++ b/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.sln @@ -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 diff --git a/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.vcproj b/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.vcproj index 1004a2c..41a95e9 100644 --- a/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.vcproj +++ b/examples/ApiExample.cpp/build/vs2005/OhlohApiExample.vcproj @@ -2,9 +2,9 @@ diff --git a/examples/ApiExample.cpp/temp.xml b/examples/ApiExample.cpp/temp.xml index c567921..74091dd 100644 --- a/examples/ApiExample.cpp/temp.xml +++ b/examples/ApiExample.cpp/temp.xml @@ -5,7 +5,7 @@ 114148 Jim Berets - 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 info@openhub.net. + 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 info@openhub.net. jberets 2010-10-06T16:15:18Z 2013-07-10T19:20:03Z diff --git a/examples/ApiExample.java b/examples/ApiExample.java index 3fde93a..c2234a6 100644 --- a/examples/ApiExample.java +++ b/examples/ApiExample.java @@ -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 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//api_keys/new diff --git a/examples/README.md b/examples/README.md index cf9c4ab..61ae0d1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,10 +1,10 @@ -## 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 rluckey@blackducksoftware.com` @@ -12,7 +12,7 @@ Some basic [Ohloh](https://www.openhub.net) API samples to help you get started. * 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: @@ -20,7 +20,7 @@ Some basic [Ohloh](https://www.openhub.net) API samples to help you get started. * 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: @@ -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: @@ -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: @@ -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: @@ -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. diff --git a/examples/account_sample.pl b/examples/account_sample.pl index 730c60e..28c3da7 100755 --- a/examples/account_sample.pl +++ b/examples/account_sample.pl @@ -4,7 +4,7 @@ =head1 NAME -account_sample.pl - Simple example of using the Ohloh API from Perl +account_sample.pl - Simple example of using the Open Hub API from Perl =head1 SYNOPSIS @@ -12,14 +12,14 @@ =head1 SYNOPSIS =head1 DESCRIPTION -This is a small example of how to use the Ohloh API from Perl, +This is a small example of how to use the Open Hub API from Perl, mimicking the Ruby example - account_sample.rb -Detailed information about the Ohloh API can be found at +Detailed information about the Open Hub API can be found at https://github.com/blackducksw/ohloh_api The script takes an API key and the email address of a developer -registered on Ohloh as parameters, and prints out all the +registered on Open Hub as parameters, and prints out all the information of that account. =head1 EXAMPLE @@ -29,7 +29,7 @@ =head1 EXAMPLE =head1 DEPENDENCIES This script uses -L (to query the Ohloh website), +L (to query the Open Hub website), L (to MD5s the email address as requested by the API) and L (to parse the server's answer). @@ -80,7 +80,7 @@ =head1 LICENCE AND COPYRIGHT $url .= '?' . join '&' => "v=$API_VERSION", "api_key=$api_key"; # request the url from the server -my $response = get $url or die "Ohloh server didn't return anything\n"; +my $response = get $url or die "Open Hub server didn't return anything\n"; # parse the XML response my $xml = eval { XMLin($response) } or die "Server didn't return valid XML\n"; diff --git a/examples/account_sample.py b/examples/account_sample.py index f097b3f..0af09c7 100755 --- a/examples/account_sample.py +++ b/examples/account_sample.py @@ -25,7 +25,7 @@ """ """ -This is an example of using the Ohloh API from Python. +This is an example of using the Open Hub API from Python. Detailed information can be found on GitHub: @@ -36,12 +36,12 @@ http://effbot.org/zone/element-index.htm -This example retrieves basic Ohloh account information +This example retrieves basic Open Hub account information and outputs it as simple name: value pairs. -Pass your Ohloh API key as the first parameter to this script. -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 script. +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//api_keys/new @@ -59,7 +59,7 @@ email = hashlib.md5() email.update(sys.argv[2]) -# Connect to the Ohloh website and retrieve the account data. +# Connect to the Open Hub website and retrieve the account data. params = urllib.urlencode({'api_key': sys.argv[1], 'v': 1}) url = "https://www.openhub.net/accounts/%s.xml?%s" % (email.hexdigest(), params) f = urllib.urlopen(url) @@ -67,11 +67,11 @@ # Parse the response into a structured XML object tree = ET.parse(f) -# Did Ohloh return an error? +# Did Open Hub return an error? elem = tree.getroot() error = elem.find("error") if error != None: - print 'Ohloh returned:', ET.tostring(error), + print 'Open Hub returned:', ET.tostring(error), sys.exit() # Output all the immediate child properties of an Account diff --git a/examples/account_sample.rb b/examples/account_sample.rb index 03a9932..0d19529 100644 --- a/examples/account_sample.rb +++ b/examples/account_sample.rb @@ -25,8 +25,8 @@ # 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 Ruby. -# Detailed information can be found at the Ohloh website: +# This is an example of using the Open Hub API from Ruby. +# Detailed information can be found at the Open Hub website: # # https://github.com/blackducksw/ohloh_api # @@ -35,12 +35,12 @@ # http://www.germane-software.com/software/rexml/ # -# This example retrieves basic Ohloh account information +# This example retrieves basic Open Hub account information # and outputs it as simple name: value pairs. # -# Pass your Ohloh API key as the first parameter to this script. -# 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 script. +# 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//api_keys/new # @@ -55,7 +55,7 @@ email = ARGV[1] # -# Connect to the Ohloh website and retrieve the account data. +# Connect to the Open Hub website and retrieve the account data. # # We pass the MD5 hash of the email address @@ -75,7 +75,7 @@ # Parse the response into a structured XML object xml = REXML::Document.new(response.body) -# Did Ohloh return an error? +# Did Open Hub return an error? error = xml.root.get_elements('/response/error').first if error STDERR.puts "#{error.text}" diff --git a/examples/account_sample.sh b/examples/account_sample.sh index c919ff9..0639b5d 100755 --- a/examples/account_sample.sh +++ b/examples/account_sample.sh @@ -22,18 +22,18 @@ # 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 Bash. +# This is an example of using the Open Hub API from Bash. # Detailed information can be found on GitHub: # # https://github.com/blackducksw/ohloh_api # -# This example retrieves basic Ohloh account information +# This example retrieves basic Open Hub account information # and outputs it as simple name: value pairs. # -# Pass your Ohloh API key as the first parameter to this script. -# 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 script. +# 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//api_keys/new # @@ -50,11 +50,11 @@ API_KEY=$1 echo $2 | grep -q -E -e'.+@.+\..+' || usage EMAIL_MD5=`echo -n $2 | openssl md5 | cut -f2 -d" "` -# Pass the MD5 hash of the email address to Ohloh. +# Pass the MD5 hash of the email address to Open Hub. # A quick-and-dirty sed filter converts the XML response to name:value pairs # -# We use the --fail option so that curl will return a non-zero exit status if Ohloh returns an error. -# This also means that the error message text returned from Ohloh will be suppressed from the output. +# We use the --fail option so that curl will return a non-zero exit status if Open Hub returns an error. +# This also means that the error message text returned from Open Hub will be suppressed from the output. curl --fail -s "https://www.openhub.net/accounts/$EMAIL_MD5.xml?v=1&api_key=$API_KEY" | sed -n 's/ *<\(.*\)>\(.*\)<\/\1>$/\1: \2/ p' # Forward along the exit status from curl diff --git a/examples/oauth2/README.md b/examples/oauth2/README.md index 726a3f2..32b7771 100644 --- a/examples/oauth2/README.md +++ b/examples/oauth2/README.md @@ -1,17 +1,17 @@ -## Using OAuth 2.0 with the OpenHub API +## Using OAuth 2.0 with the Open Hub API ### What is OAuth 2.0? -[OAuth 2.0](http://oauth.net/2) is the next evolution of the OAuth protocol. It is an open protocol that allows applications and websites to share sensitive data, without requiring you to release your password. Using OAuth, you can permit third-party applications to read from your OpenHub account without having to share your password. +[OAuth 2.0](http://oauth.net/2) is the next evolution of the OAuth protocol. It is an open protocol that allows applications and websites to share sensitive data, without requiring you to release your password. Using OAuth, you can permit third-party applications to read from your Open Hub account without having to share your password. -Instead of handing out your OpenHub account password to a third-party application, you visit the OpenHub website directly and grant that application permission to access your OpenHub account. You can revoke this permission any time you change your mind. +Instead of handing out your Open Hub account password to a third-party application, you visit the Open Hub website directly and grant that application permission to access your Open Hub account. You can revoke this permission any time you change your mind. ### Using OAuth 2.0 -In order to become OpenHub OAuth consumer, you'd need to get your key and secret from your [API Keys](https://www.openhub.net/accounts/me/api_keys) page. +In order to become Open Hub OAuth consumer, you'd need to get your key and secret from your [API Keys](https://www.openhub.net/accounts/me/api_keys) page. The application [ohloh_oauth2_sinatra.rb](/examples/oauth2/ohloh_oauth2_sinatra.rb) is a simple [Sinatra](http://www.sinatrarb.com/) based example using the [oauth2 gem](https://github.com/intridea/oauth2) that fetches authenticated user's [account](/reference/account.md) xml. ### Developer Information -OAuth 2.0 is an optional, additional feature of the OpenHub API that can be used to integrate OpenHub users on your website using their authenticated identity. You can read public data from OpenHub at any time using only your application’s OpenHub API Key. +OAuth 2.0 is an optional, additional feature of the Open Hub API that can be used to integrate Open Hub users on your website using their authenticated identity. You can read public data from Open Hub at any time using only your application’s Open Hub API Key. diff --git a/examples/oauth2/ohloh_oauth2_sinatra.rb b/examples/oauth2/ohloh_oauth2_sinatra.rb index eea0672..c8b1124 100644 --- a/examples/oauth2/ohloh_oauth2_sinatra.rb +++ b/examples/oauth2/ohloh_oauth2_sinatra.rb @@ -4,10 +4,10 @@ enable :sessions CALLBACK_URL = 'http://localhost:9292/callback' -# Assumes that you have set OHLOH_KEY and OHLOH_SECRET environment +# Assumes that you have set OpenHub_KEY and OpenHub_SECRET environment # variables to values from your API keys page. before do - @client = OAuth2::Client.new(ENV['OHLOH_KEY'], ENV['OHLOH_SECRET'], + @client = OAuth2::Client.new(ENV['OpenHub_KEY'], ENV['OpenHub_SECRET'], site: 'https://www.openhub.net', token_method: :post) end diff --git a/reference/account.md b/reference/account.md index a4b062b..3423f58 100644 --- a/reference/account.md +++ b/reference/account.md @@ -1,6 +1,6 @@ ## Account -An Account represents an Ohloh member. Some Account data is private, and cannot be accessed through the Ohloh API. +An Account represents an Open Hub member. Some Account data is private, and cannot be accessed through the Open Hub API. ### Properties + __id__ @@ -16,7 +16,7 @@ The unique ID for the Account. The Login handle for this account. + __created_at__ - The time at which this Account was originally created on Ohloh. + The time at which this Account was originally created on Open Hub. + __updated_at__ The time at which this Account record was last modified. @@ -34,13 +34,13 @@ The unique ID for the Account. A URL to the profile's Home page for this account. + __avatar_url__ - A URL to the profile image displayed on Ohloh pages. Currently, this is an URL to the Gravatar free image hosting service, which will resolves to a default image if the account holder is not a Gravatar member. Images are 80×80 by default. + A URL to the profile image displayed on Open Hub pages. Currently, this is an URL to the Gravatar free image hosting service, which will resolves to a default image if the account holder is not a Gravatar member. Images are 80×80 by default. + __email_sha1__ The SHA1 hex digest of the account email address. + __posts_count__ - The number of posts made to the Ohloh forums by this account. + The number of posts made to the Open Hub forums by this account. + __location__ An optional text description of this account holder’s claimed location. This text has been validated by either the Google or Yahoo geocoder web service, but the precision is variable. @@ -48,20 +48,20 @@ The unique ID for the Account. + __country_code__ A string representing the account holder’s country. This field is derived from location using either the Google or Yahoo geocoder web service. If you use this data, read the important note below. -+ __latitude__ and longitude__ ++ __latitude__ and __longitude__ Floating-point values representing the account’s latitude and longitude, suitable for use with the Google Maps API. They are available only when the account has specified a valid location. + __kudo_score__ -If this account has a KudoScore, it will appear here. New accounts may not have a KudoScore. The Ohloh seb site displays these accounts with a default KudoRank of 1. +If this account has a KudoScore, it will appear here. New accounts may not have a KudoScore. The Open Hub seb site displays these accounts with a default KudoRank of 1. + __languages__ Only available when requesting an accounts details, this node will not be returned as part of a search result list. This node contains the total language experience for this account grouped by language.Eachnode contains the following children: - __@color__ - This is the Ohloh color code for this language. If you will be displaying this data in your application it is highly recommended you use the colors returned here as these are the same colors Ohloh uses to display specific languages. + This is the Open Hub color code for this language. If you will be displaying this data in your application it is highly recommended you use the colors returned here as these are the same colors Open Hub uses to display specific languages. - __name__ - The Ohloh code name for this language, e.g. C# will be csharp and C++ will be cpp. + The Open Hub code name for this language, e.g. C# will be csharp and C++ will be cpp. - __experience_months__ - The total number of months that Ohloh has computed as experience in this language for the current Account. + The total number of months that Open Hub has computed as experience in this language for the current Account. - __total_commits__ The total number of commits made by the current Account that contained code in the current Language. - __total_lines_changed__ @@ -102,7 +102,7 @@ Lists the badges awarded to the account holder. All accounts have a Kudo Score - __level__ The numeric value of the level for the badge. Some badges are "binary", such as the Project Manager or the Organization Manager badges. These are awarded when the account holder manages a project or organization, respectively. For these types of badges, the level is '0' - __description__ - This is the description of the badge that is used for tool tips on Ohloh + This is the description of the badge that is used for tool tips on Open Hub - __image_url__ This is the URL of a 64x64 pixel icon of the badge image - __pips_url__ @@ -142,8 +142,8 @@ The account collection method supports the standard [collection request paramete Recently updated, first ### A Note about Country Codes -Ohloh preferentially uses the [Google Maps API](http://www.google.com/apis/maps/documentation/index.html) geocoder to resolve location names entered by users. `country_code` values obtained from the Google Maps API use two-letter abbreviations. +Open Hub preferentially uses the [Google Maps API](http://www.google.com/apis/maps/documentation/index.html) geocoder to resolve location names entered by users. `country_code` values obtained from the Google Maps API use two-letter abbreviations. -However, Google’s coverage is not complete, and not all countries can be resolved. For countries that cannot be resolved by the Google geocoder, Ohloh falls back to the Yahoo geocoder. These countries include the United Kingdom and China. `country_code` values obtained from Yahoo are full country names, not two-letter abbreviations. +However, Google’s coverage is not complete, and not all countries can be resolved. For countries that cannot be resolved by the Google geocoder, Open Hub falls back to the Yahoo geocoder. These countries include the United Kingdom and China. `country_code` values obtained from Yahoo are full country names, not two-letter abbreviations. -For this reason, there are two data formats intermingled in country_code. Ohloh does not use this data internally, so the data has not been cleaned and unified. +For this reason, there are two data formats intermingled in country_code. Open Hub does not use this data internally, so the data has not been cleaned and unified. diff --git a/reference/activity_fact.md b/reference/activity_fact.md index 62475d5..58029eb 100644 --- a/reference/activity_fact.md +++ b/reference/activity_fact.md @@ -5,7 +5,7 @@ An ActivityFact is a pre-computed collection of statistics about [Project](/refe An ActivityFact is derived from lower-level statistics contained in an [Analysis](/reference/analysis.md). ActivityFacts are updated whenever a [Project](/reference/project.md) is re-analyzed. -ActivityFacts are availabled only after Ohloh has downloaded and analyzed the project source code. +ActivityFacts are availabled only after Open Hub has downloaded and analyzed the project source code. ### Properties @@ -31,13 +31,13 @@ ActivityFacts are availabled only after Ohloh has downloaded and analyzed the pr ### Collection URL To get all ActivityFacts for a particular [Analysis](/reference/analysis.md): ```shell -curl https://www.openhub.net/projects/{project_id}/analyses/{analysis_id}/activity_facts.xml +curl https://www.openhub.net/p/{project_id}/analyses/{analysis_id}/activity_facts.xml ``` If you do not know the ID of the current best Analysis for a Project, you can use the `latest` as a shortcut for latest published analysis. ```shell -curl https://www.openhub.net/projects/{project_id}/analyses/latest/activity_facts.xml +curl https://www.openhub.net/p/{project_id}/analyses/latest/activity_facts.xml ``` -The call returns one Activity for each month, starting at the first month in which any code exists, and ending at the current month. If Ohloh has not created a new Analysis for this Project in a long time, the ActivityFacts for the months following the time of the last Analysis will contain zeros. +The call returns one Activity for each month, starting at the first month in which any code exists, and ending at the current month. If Open Hub has not created a new Analysis for this Project in a long time, the ActivityFacts for the months following the time of the last Analysis will contain zeros. The results cannot be paginated or filtered. Results are sorted chronologically. diff --git a/reference/analysis.md b/reference/analysis.md index c6dd8ba..ecb7bd6 100644 --- a/reference/analysis.md +++ b/reference/analysis.md @@ -16,12 +16,12 @@ The Analysis object described here contains only a few top-level metrics. Detail The unique ID of the Project measured by this Analysis. + __updated_at__ The time at which this Analysis record was last modified. -+ __logged_at__ - The time at which Ohloh queried the source control system for the source code measured by this Analysis. All commits which occured at or before this time are included. Note that the Analysis might also include some activity after this time if the project includes many [Repositories](/reference/repository.md), because not all Repositories are updated at the same time. The logged_at time is the most pessimistic time among all the Repositories included in the Project. ++ __oldest_code_set_time__ + The time at which Open Hub queried the source control system for the source code measured by this Analysis. All commits which occured at or before this time are included. Note that the Analysis might also include some activity after this time if the project includes many [Repositories](/reference/repository.md), because not all Repositories are updated at the same time. The logged_at time is the most pessimistic time among all the Repositories included in the Project. + __min_month__ - Ohloh groups most historical statistics ([ActivityFacts](/reference/activity_fact.md) and [SizeFacts](/reference/size_fact.md)) into monthly totals. min_month indicates the first month for which Ohloh has monthly historical statistics available for this project. This is typically the date of the first project commit, truncated to the beginning of its calendar month. Only the year and month fields are significant. + Open Hub groups most historical statistics ([ActivityFacts](/reference/activity_fact.md) and [SizeFacts](/reference/size_fact.md)) into monthly totals. min_month indicates the first month for which Open Hub has monthly historical statistics available for this project. This is typically the date of the first project commit, truncated to the beginning of its calendar month. Only the year and month fields are significant. + __max_month__ - The last month for which monthly historical statistics are available for this project. Depending on when this analysis was prepared, max_month usually refers to the current month, but it may be slightly older. Only the year and month fields are significant. Ohloh’s monthly statistics for max_month are usually smaller than other months because the complete month has not yet elapsed, and it reflects ongoing development work. + The last month for which monthly historical statistics are available for this project. Depending on when this analysis was prepared, max_month usually refers to the current month, but it may be slightly older. Only the year and month fields are significant. Open Hub’s monthly statistics for max_month are usually smaller than other months because the complete month has not yet elapsed, and it reflects ongoing development work. + __twelve_month_contributor_count__ The number of contributors who made at least one commit to the project source code in the twelve months leading up to and including `max_month`. + __total_contributor_count__ @@ -53,11 +53,11 @@ The Analysis object described here contains only a few top-level metrics. Detail - _@graph_url_ This is the url to the PNG image that depicts the language breakdown for the current Analysis. The colors referenced in each languages @color attribute will be used in this image. - _language_ - Not every language will have a entry. Ohloh will will combine languages that do not make up a significant percentage into a aggregate entry “N Other”. This entry can be identified by either its @color, always “000000″ or @id, always “”. + Not every language will have a entry. Open Hub will will combine languages that do not make up a significant percentage into a aggregate entry “N Other”. This entry can be identified by either its @color, always “000000″ or @id, always “”. Each language will contain the following data - - @color The color code that Ohloh uses to represent this language on the website. This color is also used in the language breakdown graph image. + - @color The color code that Open Hub uses to represent this language on the website. This color is also used in the language breakdown graph image. - @percentage The percentage of lines of code that the current language represents in the current Analysis - - @id The Ohloh language id. + - @id The Open Hub language id. ```xml @@ -72,10 +72,10 @@ The Analysis object described here contains only a few top-level metrics. Detail ### URL To get a particular Analysis for a single Project: ```shell -curl https://www.openhub.net/projects/{project_id}/analyses/{analysis_id}.xml +curl https://www.openhub.net/p/{project_id}/analyses/{analysis_id}.xml ``` A shortcut to the current best Analysis for a single Project can be made by substituting `latest` for the analysis ID: ```shell -curl https://www.openhub.net/projects/{project_id}/analyses/latest.xml +curl https://www.openhub.net/p/{project_id}/analyses/latest.xml ``` diff --git a/reference/code_location.md b/reference/code_location.md new file mode 100644 index 0000000..7e25892 --- /dev/null +++ b/reference/code_location.md @@ -0,0 +1,43 @@ +## Code Location +A Code Location represents an individual source control repository. + +Once added to the Open Hub database, a Code Location is permanent and unique. + +A Code Location is added to a [Project](project.md) by creating an [Enlistment](enlistment.md), which links the Project to the Code Location. In this way, many Projects can share the same Code Location. + +Deleting an Enlistment from a Project does not delete a Code Location, nor will it interrupt Open Hub download activity against that Code Location. The Code Location and all of its source code and metrics remain in the Open Hub database; only the Enlistment link is modified. + +### Properties + ++ __id__ + The unique ID of the Code Location. ++ __type__ + The source control type. Supported values are: + - _SvnRepository_ + Subversion + - _CvsRepository_ + CVS + - _GitRepository_ + Git + - _HgRepository_ + Mercurial + - _BzrRepository_ + Bazaar + ++ __url__ + The public URL for the source control server. ++ __module_name__ + For CVS repositories only, this is the module name. For Git repositories only, this is the branch name. For all other repository types, this element is omitted. ++ __username__ + An optional username, if one is required to access the source control server. ++ __password__ + An optional password, if one is required to access the source control server. ++ __logged_at__ + The last time the Open Hub servers successfully queried the source control server for changes. ++ __commits__ + The number of commits which the Open Hub servers have successfully downloaded from the source control server. ++ __ohloh_job_status__ + If the most recent attempt by Open Hub to query the source control server for changes failed or was interrupted, this value will be `failed`. In all other cases it is `success`. + +### URL +Code Locations cannot be directly queried at this time. Access them by using the [Enlistments](enlistment.md) methods. diff --git a/reference/contributor_fact.md b/reference/contributor_fact.md index 9941578..3c11f0f 100644 --- a/reference/contributor_fact.md +++ b/reference/contributor_fact.md @@ -6,7 +6,7 @@ A ContributorFact is part of an [Analysis](/reference/analysis.md), and is deriv A new ContributorFact is created for each Project contributor whenever a new Analysis is created for the Project. -ContributorFacts only exist after Ohloh has downloaded and analyzed the project source code. +ContributorFacts only exist after Open Hub has downloaded and analyzed the project source code. ### Properties @@ -18,15 +18,15 @@ ContributorFacts only exist after Ohloh has downloaded and analyzed the project + __contributor_name__ The name used by the author of this code when committing to the source control server. + __account_id__ - If this contribution has been claimed by an Ohloh member, the element contains the unique ID of the Ohloh [Account](/reference/account.md). Otherwise, this element is omitted. + If this contribution has been claimed by an Open Hub member, the element contains the unique ID of the Open Hub [Account](/reference/account.md). Otherwise, this element is omitted. + __account_name__ - If this contribution has been claimed by an Ohloh member, this element contains the Account name. Otherwise, this element is omitted. + If this contribution has been claimed by an Open Hub member, this element contains the Account name. Otherwise, this element is omitted. + __primary_language_id__ - The unique ID of the [Language](/reference/language.md) most often used by this contributor, measured by the number of code lines added. If this contributor has not committed any code in a language which Ohloh can recognize, this value will be null. + The unique ID of the [Language](/reference/language.md) most often used by this contributor, measured by the number of code lines added. If this contributor has not committed any code in a language which Open Hub can recognize, this value will be null. + __primary_language_nice_name__ The `nice_name` of the Language specified by `primary_language_id`. + __comment_ratio__ - The fraction of new lines added by this contributor which are comments. Note that Ohloh does not track the net lines of current code attributable to an specific individual. This statistic merely sums over all new lines added, and does not consider whether the added lines were later removed by this contributor or any other. + The fraction of new lines added by this contributor which are comments. Note that Open Hub does not track the net lines of current code attributable to an specific individual. This statistic merely sums over all new lines added, and does not consider whether the added lines were later removed by this contributor or any other. + __first_commit_time__ The time of the first commit by this contributor. + __last_commit_time__ @@ -41,21 +41,21 @@ ContributorFacts only exist after Ohloh has downloaded and analyzed the project ### URL To get a single ContributorFact based on the latest Analysis for a Project: ```shell -curl https://www.openhub.net/projects/{project_id}/contributors/{contributor_id}.xml +curl https://www.openhub.net/p/{project_id}/contributors/{contributor_id}.xml ``` This ContributorFact will include within it a collection of [ContributorLanguageFacts](/reference/contributor_language_fact.md) covering statistics for individual languages. ### Collection URL To get a list of all ContributorFacts based on the lastest Analysis for a Project: ```shell -curl https://www.openhub.net/projects/{project_id}/contributors.xml +curl https://www.openhub.net/p/{project_id}/contributors.xml ``` ContributorFacts returned from this call will not include ContributorLanguageFacts. Those can be obtained by retrieving ContributorFacts individually only. The project collection request supports the standard [collection request parameters](/README.md#collection-requests), with the following details: + __query__ - If supplied, only ContributorFacts with a matching `contributor_name` will be returned. Ohloh account names are not matched. + If supplied, only ContributorFacts with a matching `contributor_name` will be returned. Open Hub account names are not matched. + __sort__ ContributorFact collections support the following sort options: - __name__ diff --git a/reference/contributor_language_fact.md b/reference/contributor_language_fact.md index 5f87e49..e31afd8 100644 --- a/reference/contributor_language_fact.md +++ b/reference/contributor_language_fact.md @@ -8,7 +8,7 @@ The ContributorLanguageFact is very similar to a [ContributorFact](/reference/co A ContributorLanguageFact is part of an Analysis, and is derived from lower-level statistics contained within the [Analysis](/reference/analysis.md). New ContributorLanguageFacts are created for each Project contributor whenever a new Analysis is created for the Project. -ContributorLanguageFacts only exist after Ohloh has downloaded and analyzed the project source code. +ContributorLanguageFacts only exist after Open Hub has downloaded and analyzed the project source code. ### Properties @@ -23,7 +23,7 @@ ContributorLanguageFacts only exist after Ohloh has downloaded and analyzed the + __language_nice_name__ The `nice_name` of the Language measured. + __comment_ratio__ - The fraction of new lines added by this contributor in this language which are comments. Note that Ohloh does not track the net lines of current code attributable to an specific individual. This statistic merely sums over all new lines added, and does not consider whether the added lines were later removed by this contributor or any other. + The fraction of new lines added by this contributor in this language which are comments. Note that Open Hub does not track the net lines of current code attributable to an specific individual. This statistic merely sums over all new lines added, and does not consider whether the added lines were later removed by this contributor or any other. + __man_months__ The total number of calendar months in which this contributor made at least one commit using this Language. Months in which there was no activity in this Language for this contributor are not counted. + __commits__ @@ -32,6 +32,6 @@ ContributorLanguageFacts only exist after Ohloh has downloaded and analyzed the ### Collection URL To get a list of all ContributorLanguageFacts for a particular contributor, based on the lastest Analysis for a Project: ```shell -curl https://www.openhub.net/projects/{project_id}/contributors/{contributor_id}.xml +curl https://www.openhub.net/p/{project_id}/contributors/{contributor_id}.xml ``` This is the same URL used to obtain a [ContributorFact](/reference/contributor_fact.md). The ContributorFact returned by this call will include within it a collection of ContributorLanguageFacts. diff --git a/reference/enlistment.md b/reference/enlistment.md index 565b8f9..fa5922b 100644 --- a/reference/enlistment.md +++ b/reference/enlistment.md @@ -1,7 +1,7 @@ ## Enlistment -An Enlistment joins a [Project](/reference/project.md) to a source control [Repository](/reference/repository.md). +An Enlistment joins a [Project](/reference/project.md) to a source control [Code Location](/reference/code_location.md). -Once added to the Ohloh database, a Repository is permanent. However, Enlistments to that Repository may be added or removed at any time. Many Projects may share a single Repository. +Once added to the Open Hub database, a Code Location is permanent. However, Enlistments to that Code Location may be added or removed at any time. Many Projects may share a single CodeLocation. ### Properties @@ -9,10 +9,8 @@ Once added to the Ohloh database, a Repository is permanent. However, Enlistment The unique ID of the Enlistment. + __project_id__ The unique ID of the [Project](/reference/project.md). -+ __repository_id__ - The unique ID of the [Repository](/reference/repository.md). -+ __repository__ - The [Repository](/reference/repository.md) record will be included in full here. ++ __code_location__ + The [Code Location](/reference/code_location.md) record will be included in full here. ### URL To get a single Enlistment @@ -29,7 +27,7 @@ curl https://www.openhub.net/p/{project_id}/enlistments.xml The Enlistment collection method supports the standard [collection request parameters](/README.md#collection-requests) with the following details: + __query__ - If supplied, enlistments with a repository URL matching the query string will be returned. + If supplied, enlistments with a code_location URL matching the query string will be returned. + __sort__ Enlistment collections support the following sort options: - __module_name__ diff --git a/reference/factoid.md b/reference/factoid.md index b263697..8c0d8b4 100644 --- a/reference/factoid.md +++ b/reference/factoid.md @@ -2,9 +2,9 @@ A Factoid is a short, high-level bullet point delivering a simple observation about a [Project](/reference/project.md). Factoids are derived from an Analysis, and new Factoids are created for a Project every time a new [Analysis](/reference/analysis.md) is created. -On the Ohloh web site, Factoids are rendered in the Nutshell section of the project summary page. Factoids also are available in several of the sharing widgets available for embedding on websites. +On the Open Hub web site, Factoids are rendered in the Nutshell section of the project summary page. Factoids also are available in several of the sharing widgets available for embedding on websites. -A Project has factoids only if Ohloh has downloaded and analyzed its source code. +A Project has factoids only if Open Hub has downloaded and analyzed its source code. ### Properties + __id__ @@ -17,21 +17,15 @@ The unique ID of the [analysis](/reference/analysis.md) used to calculate this f The Factoid type. The possible types are defined below. + __description__ -A short, human-readable description. This is the bullet point text which appears on the Ohloh project page. +A short, human-readable description. This is the bullet point text which appears on the Open Hub project page. + __severity__ -An integer from -3 to +3 which rates the relative severity of the factoid. Negative numbers generally indicate bad news, positive numbers generally indicate good news. Ohloh uses these numbers to select icons to display beside the factoids. All factoids of the same type have the save severity. - -### URL -To get a single Factoid: -```shell -curl https://www.openhub.net/projects/{project_id}/factoids/{factoid_id}.xml -``` +An integer from -3 to +3 which rates the relative severity of the factoid. Negative numbers generally indicate bad news, positive numbers generally indicate good news. Open Hub uses these numbers to select icons to display beside the factoids. All factoids of the same type have the save severity. ### Collection URL To get a list of all current Factoids for a particular Project: ```shell -curl https://www.openhub.net/projects/{project_id}/factoids.xml +curl https://www.openhub.net/p/{project_id}/factoids.xml ``` The collection request does not support any filtering, sorting or paging. You will always receive the entire collection of factoids, ordered by descending priority. diff --git a/reference/kudo.md b/reference/kudo.md index 934f031..704804f 100644 --- a/reference/kudo.md +++ b/reference/kudo.md @@ -1,13 +1,13 @@ ## Kudo -A Kudo is a simple gesture of thanks, praise, or endorsement from an Ohloh [account](/reference/account.md) to another person. An account may send Kudos to as many people as desired. +A Kudo is a simple gesture of thanks, praise, or endorsement from an Open Hub [account](/reference/account.md) to another person. An account may send Kudos to as many people as desired. -Kudos can be sent directly to another Ohloh account, or they may be sent to a contributor on a Project who does not have an Ohloh account. This flexibility makes Kudo records slightly complex. +Kudos can be sent directly to another Open Hub account, or they may be sent to a contributor on a Project who does not have an Open Hub account. This flexibility makes Kudo records slightly complex. -When a Kudo is sent directly to an Ohloh Account, the recipient is identified by `receiver_account_id`. +When a Kudo is sent directly to an Open Hub Account, the recipient is identified by `receiver_account_id`. When a Kudo is sent to a contributor on a Project who does not have an Account, the Kudo record contains both `contributor_id` and `project_id`, which together uniquely identify the recipient. -Ocassionally, an Ohloh Account holder may claim to be a Project contributor who has some existing Kudos. When this happens, the existing Kudos become linked to the Account, and the Kudos will now have all three properties: `receiver_account_id`, `contributor_id`, and `project_id`. +Ocassionally, an Open Hub Account holder may claim to be a Project contributor who has some existing Kudos. When this happens, the existing Kudos become linked to the Account, and the Kudos will now have all three properties: `receiver_account_id`, `contributor_id`, and `project_id`. ### Properties + __created_at__ diff --git a/reference/kudo_score.md b/reference/kudo_score.md index ed9d4d3..d6b0285 100644 --- a/reference/kudo_score.md +++ b/reference/kudo_score.md @@ -1,15 +1,15 @@ ## Kudo Score -Every night, a KudoScore is generated for every Ohloh Account and Project contributor (collectively called ‘participants’ here). These scores are derived from the [Kudos](kudo.md) sent between participants. You can read a general outline of the KudoRank algorithm [here](http://blog.openhub.net/kudos/). +Every night, a KudoScore is generated for every Open Hub Account and Project contributor (collectively called ‘participants’ here). These scores are derived from the [Kudos](kudo.md) sent between participants. You can read a general outline of the KudoRank algorithm [here](http://blog.openhub.net/kudos/). -Not everyone has a KudoScore. Because KudoScores are calculated only once per day, new Accounts and contributors may not have a kudo score. On the Ohloh web site, unscored Accounts and contributors are displayed with a default KudoRank of 1. +Not everyone has a KudoScore. Because KudoScores are calculated only once per day, new Accounts and contributors may not have a kudo score. On the Open Hub web site, unscored Accounts and contributors are displayed with a default KudoRank of 1. ### Properties + __kudo_rank__ The KudoRank, which is an integer from 1 to 10. Higher ranks are better. KudoRanks are assigned on a curve, with a certain fraction of people receiving each KudoRank. + __position__ - An integer which orders all participants. The person with `position` equals 1 is the highest-ranked person on Ohloh. + An integer which orders all participants. The person with `position` equals 1 is the highest-ranked person on Open Hub. ### URL KudoScores cannot be queried directly. They are always returned within an [Account](account.md) record. diff --git a/reference/language.md b/reference/language.md index 342b5ed..35ba01c 100644 --- a/reference/language.md +++ b/reference/language.md @@ -9,31 +9,25 @@ Language statistics are updated daily. + __id__ The unique ID of the language. + __name__ - A short, unique name for the language. Primarily for internal Ohloh use. + A short, unique name for the language. Primarily for internal Open Hub use. + __nice_name__ A human-friendly name for the language. + __category__ Either code, markup, or build, which indicates that the language is either a “standard” programming language, a document markup language such as XML, or a build script such as a makefile. + __code__ - The total net lines of code, excluding comments and blank lines, written in this language across all projects on Ohloh. + The total net lines of code, excluding comments and blank lines, written in this language across all projects on Open Hub. + __comments__ - The total net comment lines written in this language across all projects on Ohloh. + The total net comment lines written in this language across all projects on Open Hub. + __blanks__ - The total net blank lines in this language across all projects on Ohloh. + The total net blank lines in this language across all projects on Open Hub. + __comment_ratio__ - A precomputed floating-point value for the percent of lines in this language that are comments, across all projects on Ohloh. + A precomputed floating-point value for the percent of lines in this language that are comments, across all projects on Open Hub. + __projects__ - The total number of Projects on Ohloh which currently include at least one line in this language. + The total number of Projects on Open Hub which currently include at least one line in this language. + __contributors__ - The total number of contributors on Ohloh who have written at least one line of code in this language that still exists today. + The total number of contributors on Open Hub who have written at least one line of code in this language that still exists today. + __commits__ - The total number of commits on Ohloh which include at least one line in this language. - -### URL -To get a single Language: -```shell -curl https://www.openhub.net/languages/{language_id}.xml -``` + The total number of commits on Open Hub which include at least one line in this language. ### Collection URL To get a paginated list of all Languages: diff --git a/reference/message.md b/reference/message.md deleted file mode 100644 index e562254..0000000 --- a/reference/message.md +++ /dev/null @@ -1,4 +0,0 @@ -## Message -- - - - -NOTICE: The journal feature has been discontinued. This API call is no longer available. -- - - - diff --git a/reference/news.md b/reference/news.md deleted file mode 100644 index 870db47..0000000 --- a/reference/news.md +++ /dev/null @@ -1,4 +0,0 @@ -## Account News -- - - - -NOTICE: The journal feature has been discontinued. This API call is no longer available. -- - - - diff --git a/reference/organization-collection.md b/reference/organization-collection.md index e33c79a..7ffa265 100644 --- a/reference/organization-collection.md +++ b/reference/organization-collection.md @@ -5,8 +5,8 @@ An organization is an entity which contains a collection of projects and account ### Properties + __name__ Organization Name + __url__ XML Api URL for the current organization. -+ __html_url__ The URL for the current organization page on OpenHub. -+ __created_at__ The time at which the organization was initially added to OpenHub. ++ __html_url__ The URL for the current organization page on Open Hub. ++ __created_at__ The time at which the organization was initially added to Open Hub. + __updated_at__ The time of most recent modification to the organization record. + __description__ The optional description of the current organization, currently limited to 800 characters. + __homepage_url__ An optional URL for the home page of the organization, e.g Apache Software Foundation (www.apache.org) diff --git a/reference/organization.md b/reference/organization.md index 7da6746..4a34607 100644 --- a/reference/organization.md +++ b/reference/organization.md @@ -5,8 +5,8 @@ An organization is an entity which contains a collection of projects and account ### Properties + __name__ Organization Name + __url__ XML API URL for the organization. -+ __html_url__ The URL for the organization page on OpenHub. -+ __created_at__ The time at which the organization was initially added to OpenHub. ++ __html_url__ The URL for the organization page on Open Hub. ++ __created_at__ The time at which the organization was initially added to Open Hub. + __updated_at__ The time of most recent modification to the organization record. + __description__ The optional description of the organization, currently limited to 800 characters. + __homepage_url__ An optional URL for the home page of the organization, e.g Apache Software Foundation (www.apache.org) diff --git a/reference/position.md b/reference/position.md index 54a20fa..e11e2d2 100644 --- a/reference/position.md +++ b/reference/position.md @@ -1,5 +1,5 @@ ## Position -A position represents a contribution or series of contributions that an account holder has made to a project within Ohloh. It corresponds to a committer ID for a source code repository for a particular project. +A position represents a contribution or series of contributions that an account holder has made to a project within Open Hub. It corresponds to a committer ID for a source code repository for a particular project. ### Properties @@ -8,11 +8,9 @@ A position represents a contribution or series of contributions that an account + __organization__ An optional field that contains the organization name for this position. This field will be filled in if the account holder has designated that this position’s contributions were made on behalf of an organization. Example: “IBM Corporation”. + __html_url__ - The url to the contributor page on Ohloh. + The url to the contributor page on Open Hub. + __created_at__ - The time at which this Position was originally created on Ohloh. -+ __updated_at__ - The time at which this Position record was last modified. + The time at which this Position was originally created on Open Hub. + __started_at__ Optional field that contains the time at which this position was started. This field may be filled in by the account holder if this position is not backed by commits (e.g. the user contributed documentation to the projects wiki or authored and submitted a patch committed by a project maintainer). + __ended_at__ diff --git a/reference/project.md b/reference/project.md index 63f2299..db24bcd 100644 --- a/reference/project.md +++ b/reference/project.md @@ -1,13 +1,13 @@ -## Project +## ProjectH A Project represents a collection of source code, documentation, and web sites treated together as a unit. It’s what most people might call an ‘application’ or ‘library’. ### Properties + __id__ The unique ID for the Project. + __name__ - The project name. Currently limited to 40 characters, and must be unique on Ohloh. + The project name. Currently limited to 40 characters, and must be unique on Open Hub. + __created_at__ - The time at which this Project was initially added to the Ohloh database. + The time at which this Project was initially added to the Open Hub database. + __updated_at__ The time of the most recent modification of this Project record. + __description__ @@ -16,10 +16,8 @@ A Project represents a collection of source code, documentation, and web sites t An optional URL to the project home page. + __download_url__ An optional URL to a website hosting project downloads. -+ __url_name__ - *Depricated* A short, unique name for this project. This name is used in Ohloh URLs. *This field will be removed in a future release* + __vanity_name__ - A short, unique name for this project. This name is used in Ohloh project URLs. + A short, unique name for this project. This name is used in Open Hub project URLs. + __medium_logo_url__ An url to the project’s 64×64 pixels logo image. + __small_logo_url__ @@ -39,7 +37,7 @@ A Project represents a collection of source code, documentation, and web sites t + __url__ The xml api url for the current Project. + __html_url__ - The url to the current Projects details page on Ohloh. + The url to the current Projects details page on Open Hub. + __factoids__ The factoids for the current analysis of the project will be included under this node. @@ -68,11 +66,11 @@ A Project represents a collection of source code, documentation, and web sites t - __@graph_url__ This is the url to the PNG image that depicts the language breakdown for the current Analysis. The colors referenced in each languages @color attribute will be used in this image. - __language__ - Not every language will have a entry. Ohloh will will combine languages that do not make up a significant percentage into a aggregate entry “N Other”. This entry can be identified by either its @color, always “000000″ or @id, always “”. + Not every language will have a entry. Open Hub will combine languages that do not make up a significant percentage into a aggregate entry “N Other”. This entry can be identified by either its @color, always “000000″ or @id, always “”. Each language will contain the following data - - @color The color code that Ohloh uses to represent this language on the website. This color is also used in the language breakdown graph image. + - @color The color code that Open Hub uses to represent this language on the website. This color is also used in the language breakdown graph image. - @percentage The percentage of lines of code that the current language represents in the current Analysis - - @id The Ohloh language id. + - @id The Open Hub language id. ```xml @@ -83,18 +81,37 @@ A Project represents a collection of source code, documentation, and web sites t ``` ++ __similar_projects__ + The similar projects with regards to the tags will be included under this node. + - __id__ + The unique ID for the Project. + - __name__ + Full Name of the project + - __vanity_url__ + A short, unique name for this project. This name is used in openhub project URLs. + +```xml + + + 1 + Ruby + ruby + + +``` + + __licenses__ The Licenses for the current project will be included under this node. - __name__ Full Name of the License - - __nice_name__ + - __vanity_url__ A human-friendly name of the License ```xml mit - MIT License + MIT License ``` @@ -124,7 +141,7 @@ A Project represents a collection of source code, documentation, and web sites t + __links__ The links associated with the current project. Homepage and Download links are not included here. - __category__ - Link category on Ohloh + Link category on Open Hub - __title__ - __url__ @@ -142,13 +159,13 @@ A Project represents a collection of source code, documentation, and web sites t ### URL To get a single Project, including its current best Analysis: ```shell -curl https://www.openhub.net/projects/{project_id}.xml +curl https://www.openhub.net/p/{project_id}.xml ``` ### Collection URL To get a list of all Projects, not including their Analyses: ```shell -curl https://www.openhub.net/projects.xml +curl https://www.openhub.net/p.xml ``` The Project collection request supports the standard [collection request parameters](/README.md#collection-requests), with the following details: diff --git a/reference/repository.md b/reference/repository.md deleted file mode 100644 index fc310d6..0000000 --- a/reference/repository.md +++ /dev/null @@ -1,45 +0,0 @@ -## Repository -A Repository represents an individual source control repository. - -Once added to the Ohloh database, a Repository is permanent and unique. - -A Repository is added to a [Project](project.md) by creating an [Enlistment](enlistment.md), which links the Project to the Repository. In this way, many Projects can share the same Repository. - -Deleting an Enlistment from a Project does not delete a Repository, nor will it interrupt Ohloh download activity against that Repository. The Repository and all of its source code and metrics remain in the Ohloh database; only the Enlistment link is modified. - -### Properties - -+ __id__ - The unique ID of the Repository. -+ __type__ - The source control type. Supported values are: - - _SvnRepository_ - Subversion - - _CvsRepository_ - CVS - - _GitRepository_ - Git - - _HgRepository_ - Mercurial - - _BzrRepository_ - Bazaar - - _SvnSyncRepository_ - Subversion ‘svnsync’ - -+ __url__ - The public URL for the source control server. -+ __module_name__ - For CVS repositories only, this is the module name. For all other repository types, this element is omitted. -+ __username__ - An optional username, if one is required to access the source control server. -+ __password__ - An optional password, if one is required to access the source control server. -+ __logged_at__ - The last time the Ohloh servers successfully queried the source control server for changes. -+ __commits__ - The number of commits which the Ohloh servers have successfully downloaded from the source control server. -+ __ohloh_job_status__ - If the most recent attempt by Ohloh to query the source control server for changes failed or was interrupted, this value will be `failed`. In all other cases it is `success`. - -### URL -Repositories cannot be directly queried at this time. Access them by using the [Enlistments](enlistment.md) methods. diff --git a/reference/size_fact.md b/reference/size_fact.md index 09c77d0..f528b52 100644 --- a/reference/size_fact.md +++ b/reference/size_fact.md @@ -5,7 +5,7 @@ SizeFacts contain the running totals of [ActivityFacts](activity_fact.md). A SizeFact is derived from lower-level statistics contained in an [Analysis](analysis.md). SizeFacts are updated whenever a [Project](project.md) is re-analyzed. -SizeFacts are availabled only after Ohloh has downloaded and analyzed the project source code. +SizeFacts are availabled only after Open Hub has downloaded and analyzed the project source code. ### Properties @@ -27,13 +27,13 @@ SizeFacts are availabled only after Ohloh has downloaded and analyzed the projec ### Collection URL To get all SizeFacts for a particular [Analysis](analysis.md): ```shell -curl https://www.openhub.net/projects/{project_id}/analyses/{analysis_id}/size_facts.xml +curl https://www.openhub.net/p/{project_id}/analyses/{analysis_id}/size_facts.xml ``` If you do not know the ID of the current best Analysis for a Project, you can use the following shortcut: ```shell -curl https://www.openhub.net/projects/{project_id}/analyses/latest/size_facts.xml +curl https://www.openhub.net/p/{project_id}/analyses/latest/size_facts.xml ``` -The call returns one SizeFact for each month, starting at the first month in which any code exists, and ending at the month in which Ohloh last created a new Analysis for this Project. Typically, the collection ends at the current month, but if the Project has not been re-analyzed in a while, the collection may end sooner. +The call returns one SizeFact for each month, starting at the first month in which any code exists, and ending at the month in which Open Hub last created a new Analysis for this Project. Typically, the collection ends at the current month, but if the Project has not been re-analyzed in a while, the collection may end sooner. The results cannot be paginated or filtered. Results are sorted chronologically. diff --git a/reference/stack.md b/reference/stack.md index cb7f31b..9caadeb 100644 --- a/reference/stack.md +++ b/reference/stack.md @@ -1,6 +1,6 @@ ## Stack -A Stack represents a collection of Projects used by a single person. A Stack belongs to an [Account](account.md). +A Stack represents a collection of Projects used by a single person. A Stack belongs to an [Account](account.md)./, A Stack contains zero or more [StackEntries](stack_entry.md), each of which links the Stack to a single [Project](project.md). @@ -21,25 +21,12 @@ A Stack contains zero or more [StackEntries](stack_entry.md), each of which link + __account_id__ The unique ID of the [Account](account.md) which owns this Stack. + __account__ - For convenience, a full [Account](account.md) object may be included here. If the stack object was returned in response to a collection request (for example, - `/projects/{project_id}/stacks.xml`), the Account objects will be present. - -### URL -To get a single Stack belonging to an Account: -```shell -curl https://www.openhub.net/accounts/{account_id}/stacks/{stack_id}.xml -``` -A handy shortcut for getting the default Stack for an Account when you don’t know the stack_id: -```shell -curl https://www.openhub.net/accounts/{account_id}/stacks/default.xml -``` -This method is not paginated — you will always receive a single Stack. However, this Stack may contain a very large number of StackEntries within it. Each StackEntry will include a full Project object. - -If you do not know the Account ID, you can also retrieve the Stack using the MD5 hash of the email address. Read more about email-based queries [here](/email_lookup.md). + For convenience, a full [Account](account.md) object may be included here. ### Collection URL To get a list of all Stacks for a particular Project: ```shell -GET https://www.openhub.net/projects/{project_id}/stacks.xml +GET https://www.openhub.net/p/{project_id}/stacks.xml ``` The Stacks returned in this collection will each contain only a single [StackEntry](stack_entry.md), corresponding to the Project in question. From 7c295ea2ad5e6635674b2dc3305d27db08c0d1cf Mon Sep 17 00:00:00 2001 From: Priya Rani Date: Wed, 15 Jan 2025 18:47:17 +0530 Subject: [PATCH 2/2] Fix typo --- LICENSE | 2 +- examples/ApiExample.java | 2 +- examples/account_sample.pl | 2 +- examples/account_sample.py | 2 +- examples/account_sample.rb | 2 +- examples/account_sample.sh | 2 +- reference/account.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/LICENSE b/LICENSE index 743a330..463eb0f 100644 --- a/LICENSE +++ b/LICENSE @@ -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 diff --git a/examples/ApiExample.java b/examples/ApiExample.java index c2234a6..4125325 100644 --- a/examples/ApiExample.java +++ b/examples/ApiExample.java @@ -24,7 +24,7 @@ of this software and associated documentation files (the "Software"), to deal 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. diff --git a/examples/account_sample.pl b/examples/account_sample.pl index 28c3da7..fed9964 100755 --- a/examples/account_sample.pl +++ b/examples/account_sample.pl @@ -16,7 +16,7 @@ =head1 DESCRIPTION mimicking the Ruby example - account_sample.rb Detailed information about the Open Hub API can be found at -https://github.com/blackducksw/ohloh_api +https://github.com/blackducksoftware/ohloh_api The script takes an API key and the email address of a developer registered on Open Hub as parameters, and prints out all the diff --git a/examples/account_sample.py b/examples/account_sample.py index 0af09c7..513f1db 100755 --- a/examples/account_sample.py +++ b/examples/account_sample.py @@ -29,7 +29,7 @@ Detailed information can be found on GitHub: - https://github.com/blackducksw/ohloh_api + https://github.com/blackducksoftware/ohloh_api This example uses the ElementTree library for XML parsing (included in Python 2.5 and newer): diff --git a/examples/account_sample.rb b/examples/account_sample.rb index 0d19529..9d276d8 100644 --- a/examples/account_sample.rb +++ b/examples/account_sample.rb @@ -28,7 +28,7 @@ # This is an example of using the Open Hub API from Ruby. # Detailed information can be found at the Open Hub website: # -# https://github.com/blackducksw/ohloh_api +# https://github.com/blackducksoftware/ohloh_api # # This example uses the REXML library for XML parsing: # diff --git a/examples/account_sample.sh b/examples/account_sample.sh index 0639b5d..2df608f 100755 --- a/examples/account_sample.sh +++ b/examples/account_sample.sh @@ -25,7 +25,7 @@ # This is an example of using the Open Hub API from Bash. # Detailed information can be found on GitHub: # -# https://github.com/blackducksw/ohloh_api +# https://github.com/blackducksoftware/ohloh_api # # This example retrieves basic Open Hub account information diff --git a/reference/account.md b/reference/account.md index 3423f58..1dad900 100644 --- a/reference/account.md +++ b/reference/account.md @@ -52,7 +52,7 @@ The unique ID for the Account. Floating-point values representing the account’s latitude and longitude, suitable for use with the Google Maps API. They are available only when the account has specified a valid location. + __kudo_score__ -If this account has a KudoScore, it will appear here. New accounts may not have a KudoScore. The Open Hub seb site displays these accounts with a default KudoRank of 1. +If this account has a KudoScore, it will appear here. New accounts may not have a KudoScore. The Open Hub web site displays these accounts with a default KudoRank of 1. + __languages__ Only available when requesting an accounts details, this node will not be returned as part of a search result list. This node contains the total language experience for this account grouped by language.Eachnode contains the following children: