The Open DRadio REST API - https://api.opendradio.org.
Build with the use of Slim Framework, Eloquent ORM with support for Facades, MongoDB and Redis caching.
Facades provide a "static" interface to classes that are available in Laravel's IoC container. They serve as "static proxies" to underlying classes in the service container, providing the benefit of a terse, expressive syntax while maintaining more testability and flexibility than traditional static methods.
This API uses the Redis PHP extension to enable in-memory caching for MongoDB query results.
You can flush the cache with redis-cli:
$ redis-cli flushallSchema
With the API, the general format of a response is:
{
"success": true,
"message": "200 OK",
"data": { "..." }
}However, data may contain any kind of result, depending on the method.
Client Errors
If the API encounters an error, the response will be:
{
"success": false,
"message": "404 Not Found"
}You can issue a GET request to the root endpoint to get all the endpoints that the API supports:
$ curl https://api.opendradio.org/v1/To promote Google's "Let's make the web faster" initiative, the API supports the SPDY transport protocol.
$ openssl s_client -connect api.opendradio.org:443 -nextprotoneg ''
CONNECTED(00000003)
Protocols advertised by server: spdy/3.1, http/1.1| Verb | Description |
|---|---|
GET |
Used for retrieving resources. |
POST |
Used for creating resources. |
PATCH |
Used for updating resources with partial JSON data. For instance, an resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests. |
DELETE |
Used for deleting resources. |
The default date format for this API is W3C (also known as RFC3339).
Y-m-d\TH:i:sPTime Zone
The default time zone is UTC+1 (Europe/Berlin), since it is the location of Deutschlandradio headquarters.
Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter, see Geo Frequencies for example.
$ curl 'https://api.opendradio.org/v1/news/from/2015-08-15/to/2015-08-17?page=2&per_page=10'Requests that return multiple items can be sorted ascending asc or descending desc with the ?sort parameter.
$ curl 'https://api.opendradio.org/v1/broadcasts/latest?sort=desc'GET /playlistParameters
| Name | Type | Description |
|---|---|---|
sort |
string |
The direction of the sort. Can be either asc or desc. Default: asc (newest first) |
permanent |
boolean |
Either true or ✓ to show only permanent stations, false to show temporary stations. |
Response
{
"success": true,
"message": "200 OK",
"data": [
{
"_id": "4af9f23d8emd0e1d32000000",
"title": "Deutschlandfunk",
"name": "dlf",
"slug": "deutschlandfunk",
"permanent": true,
"website": "http://example.com/",
"updated_at": "2015-08-15T15:52:01+01:00",
"streams": [
{
"type": "ogg",
"quality": "hq",
"bitrate": 96,
"url": "http://example.com/link-to-ogg"
},
{
"type": "mp3",
"quality": "hq",
"bitrate": 128,
"url": "http://example.com/link-to-mp3"
}
]
}
]
}GET /broadcasts/latestParameters
| Name | Type | Description |
|---|---|---|
sort |
string |
The direction of the sort. Can be either asc or desc. Default: asc (newest first) |
station |
string |
Indicates the station of the items to return. Can be one of:
all |
Response
{
"success": true,
"message": "200 OK",
"data": [
{
"_id": "4af9f23d8ead0f1d32000000",
"title": "Lorem ipsum dolor sit amet",
"starts_at": "2015-08-15T15:35:00+01:00",
"type": "branchy",
"ends_at": "2015-08-15T16:00:00+01:00",
"duration": 1500,
"full_duration": 14100,
"part": 5,
"parent_id": "4af9f23d8ead0f1d31000000",
"description": "...",
"station_id": "4af9f23d8emd0e1d32000000",
"updated_at": "2015-08-15T15:52:01+01:00"
}
]
}GET /broadcasts/from/2015-08-15/to/2015-08-17Parameters
| Name | Type | Description |
|---|---|---|
sort |
string |
The direction of the sort. Can be either asc or desc. Default: asc (newest first) |
station |
string |
Indicates the station of the items to return. Can be one of:
all |
page |
number |
Results will be limited to 30 items by default. You can specify further pages. Default: 1 |
per_page |
number |
Indicates how many items you want each page to return. Default: 30 |
GET /broadcasts/id/4af9f23d8ead0e1d32000000GET /news/latestParameters
| Name | Type | Description |
|---|---|---|
sort |
string |
The direction of the sort. Can be either asc or desc. Default: asc (newest first) |
station |
string |
Indicates the station of the items to return. Can be one of:
all |
Response
{
"success": true,
"message": "200 OK",
"data": [
{
"_id": "4af9f23d8ead0f1d32000000",
"title": "Lorem ipsum dolor sit amet",
"text": "...",
"publicated_at": "2015-08-15T15:52:01+01:00",
"station_id": "4af9f23d8emd0e1d32000000",
"updated_at": "2015-08-15T15:52:01+01:00"
}
]
}GET /news/from/2015-08-15/to/2015-08-17Parameters
| Name | Type | Description |
|---|---|---|
sort |
string |
The direction of the sort. Can be either asc or desc. Default: asc (newest first) |
station |
string |
Indicates the station of the items to return. Can be one of:
all |
page |
number |
Results will be limited to 30 items by default. You can specify further pages. Default: 1 |
per_page |
number |
Indicates how many items you want each page to return. Default: 30 |
GET /news/id/4af9f23d8ead0e1d32000000GET /geo-frequenciesResponse
{
"success": true,
"message": "200 OK",
"data": [
{
"country": "BE",
"states": [
{
"state": "DE-BE",
"cities": [
{
"_id": "4af9f23d8emd0e1d31000000",
"city": "Berlin",
"coords": {
"latitude": 52.5200066,
"longitude": 13.404954
},
"frequencies": [
{
"_id": "4af9f23d8emd0e1d31000001",
"station_id": "4af9f23d8emd0e1d32000000",
"vhf": "97.7"
},
{
"_id": "4af9f23d8emd0e1d31000002",
"mf": "990",
"station_id": "4af9f23d8emd0e1d32000000"
},
{
"_id": "4af9f23d8emd0e1d31000002",
"station_id": "54af9f23d8emd0e1d33000000",
"vhf": "89.6"
}
],
"updated_at": "2015-08-15T15:52:01+01:00"
}
]
}
]
}
]
}
You need PHP >= 5.4 for this to work predictably.
Running the application requires the latest version of Composer to install the dependencies.
-
Composer - Dependency Manager for PHP. Installing Composer is easy:
$ curl -sS https://getcomposer.org/installer | php -
MongoDB
>= 2.6.6- The leading NoSQL database. -
Redis
>= 2.8.19- An advanced key-value cache and store.
-
Change to the top-level project directory.
-
Install the dependencies:
$ composer update
Your environment is now ready to work on the source.
You need the latest version of PHPUnit for this to work predictably. Read the Getting Started guide for installation instructions.
How to run the tests:
-
Install the latest version of PHPUnit.
-
Run PHPUnit tests - From the top-level project directory change to the
app/testsdirectory. You may run all unit tests or specific unit tests. -
Start the test runner:
$ phpunit tests
All unit tests require PHP >= 5.4.
Open DRadio is an non-profit, open source, community-driven project.
This code is open-sourced software licensed under the AGPL-3.0 license.