index.apib

FORMAT: 1A
HOST: https://api.eclipse.org

# Eclipse RESTful API
This describes the resources that make up the official Eclipse Foundation REST API. 

If you have any problems or requests please contact [Christopher Guindon](mailto:chris.guindon@eclipse-foundation.org) .

### Rate Limit
This API currently limits users to 1000 authenticated requests and 1000 anonymous requests an hour.

### Pagination
Information about pagination is provided in the Link header of an API call. For example, let’s make 
a curl request to the eclipse_profile API, to find out how many org_eclipse_oomph records exist for the user:

```curl -I "https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=1&pagesize=2"```
 
The -I parameter indicates that we only care about the headers, not the content. 
In examining the result, you’ll notice some information in the Link header that looks like this:
 
```
<https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=2&amp;pagesize=2>; rel="next", <https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=27&amp;pagesize=2>; rel="last", <https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=1&amp;pagesize=2>; rel="first", <https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=1&amp;pagesize=2>; rel="self"
```
 
Let’s break that down. rel="next" says that the next page is page=2. This makes sense, since by default, 
all paginated queries start at page 1. rel="last" provides some more information, stating that the last page of results is on page 27. 
 
Keep in mind that you should always rely on these link relations provided to you. Don’t try to guess or construct your own URL.

### Caching

Most responses return an ETag header. You can use the values of these headers to make subsequent 
requests to those resources using the If-None-Match or if-Match header. For example, if the resource 
has not changed on a GET, the server will return a 304 Not Modified.
 
The Etag for a blob resource is predictable. This is how were are currently generating them:

```
function _generate_etag($value, $application_token, $key) {
  $string = $value . $application_token . $key;
  return  hash('sha256', $string, FALSE);
}
```

### Authentication
*Eclipse Api RESTful API* uses OAuth2 Authorization for protected resources.

### Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) 
are used.

<!-- include(modules/account.apib) -->
<!-- include(modules/uss.apib) -->
<!-- include(modules/download.apib) -->
<!-- include(modules/marketplace_favorites.apib) -->
<!-- include(modules/oauth2.apib) -->