Introduction
El Nuevo Dia (END) exposes some of its content and functionality via an Application Programming Interface (API) built and supported by APEX Technologies, Inc. This document is a reference for that interface, and aims to serve as a reference for developers building tools that talk to the END Interactive API (ENDIAPI). For more information about this document or the API please contact us at: .
Contents
Introduction
Concepts
Authentication
RESTful Resources
Parameters
HTTP Requests
HTTP Headers
HTTP Status Codes
Error Messages
Rate Limiting
Pagination Limiting
Encoding
Getting Started
Be Nice to the Servers
The Easiest Way to Play Around with the ENDIAPI
Sample code
Frequently Asked Questions
How do I report bugs and request features?
How can I keep up with changes to the ENDIAPI?
Resources Available From API
Sections
Description
Methods
Subsections
Description
Methods
News
Description
Methods
Comments
Description
Methods
Photogalleries
Description
Methods
Horoscopes
Description
Methods
Polls
Description
Methods
Concepts
Authentication
Many ENDIAPI methods require authentication. All responses are relative to the context of the authenticating user.
For the time being, HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth, use your username and password in the Authorization header and provide the API Key in the request header.
See examples for more information.
RESTful Resources
The ENDIAPI attempts to conform to the design principles of Representational State Transfer (REST).
ENDIAPI presently only supports JSON as its data format.
Parameters
Some API methods take optional or requisite parameters. Where applicable, we’ve documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings. Please note that the page parameter begins at 1, not 0.
There are two special parameters in the ENDIAPI:
- callback: Used only when requesting JSON formatted responses, this parameter wraps your response in a callback method of your choice. For example, appending &callback=myFancyFunction to your request will result in a response body of: myFancyFunction(...). Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.
- suppress_response_codes: If this parameter is present, all responses will be returned with a 200 OK status code - even errors. This parameter exists to accommodate Flash and JavaScript applications running in browsers that intercept all non-200 responses. If used, it's then the job of the client to determine error states by parsing the response body. Use with caution, as those error messages may change.
HTTP Requests
Methods to retrieve data from the ENDIAPI require a GET request. Methods that submit, change, or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method.
Currently only GET is supported.
HTTP Headers
Where noted, some API methods will return different results based on HTTP headers sent by the client. For example, most methods that allow a since parameter will also respond to an If-Modified-Since header. Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.
HTTP Status Codes
The ENDIAPI attempts to return appropriate HTTP status codes for every request. Here's what's going on with our various status codes:
- 200 OK: everything worked as expected.
- 304 Not Modified: there was no new data to return.
- 400 Bad Request: your request is invalid, and we'll return an error message that tells you why. This is the status code returned if you've exceeded the rate limit (see below).
- 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren't valid.
- 403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
- 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such news item).
- 410 Gone: This will be the status code returned when the resource you are requesting is no longer available and will not be available ever again, such as a news item that has expired.
- 500 Internal Server Error: we did something wrong. Please post to the group about it and the APEX team will investigate.
- 502 Bad Gateway: returned if ENDIAPI is down or being upgraded.
- 503 Service Unavailable: the ENDAPI servers are up, but are overloaded with requests. Try again later.
Error Messages
When the ENDI API returns error messages, it does so in JSON.
{
“request” : “/news/3123/”,
“error” : “No news article with that ID found.”
}
Rate Limiting
Clients are allowed 100 requests per 60 sixty minute time period, starting from their first request.
Notification that a client has exceeded the rate limit will be sent as JSON. A status code of 400 will be returned when the client has exceeded the rate limit.
If you are developing an application that requires more frequent requests to the ENDIAPI, please request whitelisting to APEX and we'll get back to you, usually within 48 hours or less.
Pagination Limiting
Clients may request up to the last 31 days of news articles via the page and count parameters. Requests for more than the limit will result in a reply with a status code of 200 and an empty result in the format requested.
Encoding
The ENDIAPI supports UTF-8 encoding.
Getting Started
Be Nice to the Servers
In order to keep the API running smoothly, please obey the following guidelines:
- If your application does not keep local state, request only the first page of information that you need, and load additional pages only when triggered by user interaction.
- If your application keeps a local archive that persists between sessions, it's okay to request an entire list. Save it locally and avoid requesting it again.
- Cache your data! and keep an eye on the remaining requests remember you only have a certain amount of request per hour.
The Easiest Way to Play Around with the ENDIAPI
If your system has curl (and it should!), you’ve already got a great way to poke around the ENDIAPI. Here are some examples:
- Get the section information: curl -u <username>:<password> –H “api_key: <APIKey>”
- Get information about the section with id “1”: curl -u <username>:<password> –H “api_key: <APIKey>”
Sample code
using System;
using System.Web;
using System.IO;
using System.Net;
using System.Text;
// Create the web request
HttpWebRequest request = WebRequest.Create(" as HttpWebRequest;
// Add pre authentication to request
request.PreAuthenticate = true;
// Add Authorization header
request.Headers.Add(HttpRequestHeader.Authorization, "Basic " + Convert.ToBase64String(
new UTF8Encoding().GetBytes(String.Format("{0}:{1}", "<Username>", "Password"))));
// Add API Key to header
request.Headers.Add(String.Format("api_key:{0}", "<API Key>"));
// Get response
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse) {
// Get the response stream
StreamReader reader = new StreamReader(response.GetResponseStream());
// Console application output
Console.WriteLine(reader.ReadToEnd());
}
Frequently Asked Questions
How do I report bugs and request features?
You can see the list of existing issues right here. Please check to be sure your issue hasn't already been reported. Star an existing issue to vote for it, or add an example to an issue if it describes your bug. Or, report a new issue if need be.
How can I keep up with changes to the ENDIAPI?
There are a number of great ways to follow the changes we make to the ENDIAPI:
- Follow @endiapi on Twitter.
- Check the REST API Changelog right here on the API Wiki or subscribe to its RSS feed.
Resources Available From API
Sections
Description
Sections are a container item that has subsections within them and a short description of the section itself.
Here’s an example of a section as defined in JSON:
{
“id” : “1”,
“name” : “Diario”,
“url” : “
“subsections” : [
{
“id” : 1,
“name” : “PR Hoy”,
“path” : “/sections/noticias/subsections/prhoy/”,
},
{
“id” : 2,
“name” : “Negocios”,
“path” : “/sections/noticias/subsections/negocios/”,
},
…
{
“id” : 8,
“name” : “Ciencia y Tecnología”,
“path” : “/sections/noticias/subsections/cienciaytecnologia/”,
}
]
}
Some notes:
- Id: The internal id (integer) of the section, this can also be used to access the Section resource.
- Subsections: an array of the id, name and path of the subsections belonging to this section.
- url: defines the url for the section’s site in elnuevodia.com
Methods
/sections/
Returns the list of section objects corresponding to all the sections in El Nuevo Dia.
URL:
Parameters: NONE
Example output:
[{
“id” : 1,
“name” : “Noticias”,
“url” : “
“subsections” : [
{
“id” : 1,
“name” : “PR Hoy”,
“path” : “/sections/noticias/subsections/prhoy/”,
},
…
]
},{
“id” : 2,
“name” : “Deportes”,
“url” : “
“subsections” : […]
}]
Subsections
Description
Subsections are a container item that contains paths to news items.
Here’s an example of a subsection as defined in JSON:
{
“id” : 1,
“section_id” : 1,
“name” : “PR Hoy”,
“url” : “
“news” : [
{
“title” : “Primera Noticia Del Dia”,
“subtitle” : “Todo el mundo feliz porque puede ver El Nuevo Día a través de REST.”,
“path” : “/news/1/”,
},
…
]
}
Some notes:
- Id: The internal id (integer) of the subsection, this can also be used to access the Subsection resource.
- News: It’s a list of the title, subtitle and paths of the news items belonging to this section.
- url: defines the url for the subsection’s site in elnuevodia.com
Methods
/sections/<section_id>/subsections/
Returns the list of subsection objects corresponding to the section with id <section_id>.
URL:
Example URL(s):
Parameters: NONE
Example output:
[{
“id” : “1”,
“section_id” : “1”,
“name” : “PR Hoy”,
“url” : “
“news” : [ … ],
},
{
“id” : “2”,
“section_id” : “1”,
“name” : “Negocios”,
“url” : “
“news” : [ … ],
},]
News
Description
News items are an object that describes a news article in depth and all the resources related to it.
Here’s an example of a news article as defined in JSON:
{
“id” : 1,
“section_id” : 1,
“subsection_id” : 1,
“url” : “
“title” : “Primera Noticia Del Dia”,
“subtitle” : “Todo el mundo feliz porque puede ver El Nuevo Día a través de REST.”,
“intro” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“author” : “Tyler Durden”,
“body” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“related_news” : [ 2, 3, 4, 5, 6 … ],
“related_photogalleries” : [ 1 ],
“related_polls” : [ 1 ],
“image” : { “url”: “
“title” : “REST Diagram”,
“caption” : “REpresentational State Transfer is the architecture behind El Nuevo Día’s powerful API.”,
“alt_text” : “A REpresentational State Transfer Diagram”,
}
“tags” : [“rest”, “programming”, “api”, “endi”, “apex”],
“pub_date” : “YYYY-MM-DD”,
“mod_date” : “YYYY-MM-DD”
}
Some notes:
- Id: The internal id (integer) of the section.
- Section_id: the integer id of the section containing this news article
- subsection_id: the integer id of the subsection containing this news article
- related_news (optional): an array of ids of news articles related to this one
- related_photogalleries (optional): an array of ids of photogalleries related to this news item (typically only a single gallery)
- related_polls (optional): an array of ids of polls related to this news item (typically only a single poll)
- image (optional): an image JSON object describing an image related to this news item
- tags: array of string tags describing the article
- pub_date/mod_date: ISO 8601 formatted string with the publication and last modification dates
Methods
/news/
Returns a list of the news articles, by default it returns the last 10 news articles sorted by date.
URL:
Example URL(s):
Parameters:
- count(optional): amount (int) of results to return (max 50, defaults to 10)
- get_related_news (optional): set this to true to expand the related_news array to include the JSON object with all the data instead of just having the IDs. Use this instead of multiple queries if you’re always going to query the related news articles. (default: false)
- get_related_photogalleries (optional): set this to true to expand the related_ photogalleries array to include the JSON object with data instead of just having the IDs. Use this instead of multiple queries if you’re always going to query the related photogalleries.
- get_related_polls (optional): set this to true to expand the related_polls array to include the JSON object with data instead of just having the IDs. Use this instead of multiple queries if you’re always going to query the related polls.
- mod_date_start(optional): ISO 8601 formatted string for the start of the modification dates to search for (only the last 7 days are available)
- mod_date_end(optional): ISO 8601 formatted string for the end of the modification dates to search for
- page(optional): page of results to return (defaults to 1).
- pub_date_start(optional): ISO 8601 formatted string for the start of the publication dates to search for
- pub_date_end(optional): ISO 8601 formatted string for the end of the publication dates to search for
- section(optional): section (int id) to filter by
- source(optional): source (“print” or “web”) to filter by
- subsection(optional): subsection (int id) to filter by
- tags(optional): a comma separated list of tags to filter by
Example output:
[{
“id” : 1,
“section_id” : 1,
“subsection_id” : 1,
“title” : “Primera Noticia Del Dia”,
“subtitle” : “Todo el mundo feliz porque puede ver El Nuevo Día a través de REST.”,
“intro” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“author” : “Tyler Durden”,
“body” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“related_news” : [ 2, 3, 4, 5, 6 ],
“related_photogalleries” : [ 1 ],
“related_polls” : [ 1 ],
“image” : { “url”: “
“title” : “REST Diagram”,
“caption” : “REpresentational State Transfer is the architecture behind El Nuevo Día’s powerful API.”,
“alt_text” : “A REpresentational State Transfer Diagram”,
}
“tags” : [“rest”, “programming”, “api”, “endi”, “apex”],
“pub_date” : “2008-01-12”,
“mod_date” : “2009-01-13”
},
{…},
]
/news/<id>/
Returns the news article with id equal to <id>.
URL: /
Example URL(s):
Parameters: NONE
Example output:
{
“id” : 1,
“section_id” : 1,
“subsection_id” : 1,
“title” : “Primera Noticia Del Dia”,
“subtitle” : “Todo el mundo feliz porque puede ver El Nuevo Día a través de REST.”,
“intro” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“author” : “Tyler Durden”,
“body” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“related_news” : [ 2, 3, 4, 5, 6 ],
“related_photogalleries” : [ 1 ],
“related_polls” : [ 1 ],
“image” : { “url”: “
“title” : “REST Diagram”,
“caption” : “REpresentational State Transfer is the architecture behind El Nuevo Día’s powerful API.”,
“alt_text” : “A REpresentational State Transfer Diagram”,
}
“tags” : [“rest”, “programming”, “api”, “endi”, “apex”],
“pub_date” : “2008-01-12”,
“mod_date” : “2009-01-13”
}
Comments
Description
A comment items is an object describing a comment on a news article.
Here’s an example of a news article as defined in JSON:
{
“id” : 1,
“text” : “Primera Noticia Del Dia”,
“author” : “Tyler Durden”,
“post_date” : “2008-01-20 13:02:23-04”,
}
Some notes:
- Id: The internal id (integer) of the comment.
- Text: a string containing the text of the comment
- Author: the username of the author that posted the comment
- post_date: ISO 8601 formatted string with the comment post date
Methods
/news/<id>/comments/
Returns a list of the comments for a particular news article, by default it returns the last 10 news articles sorted by date.
URL:
Example URL(s):
Parameters:
- count(optional): amount (int) of results to return (max 25, defaults to 10)
- page(optional): page of results to return (defaults to 1).
- post_date_start(optional): ISO 8601 formatted string for the start of the publication dates to search for
- post_date_end(optional): ISO 8601 formatted string for the end of the publication dates to search for
- section(optional): section (int id) to filter by
- source(optional): source (“print” or “web”) to filter by
- subsection(optional): subsection (int id) to filter by
- tags(optional): a comma separated list of tags to filter by
Example output:
[{
“id” : 1,
“text” : “Primera Noticia Del Dia”,
“author” : “Tyler Durden”,
“post_date” : “2008-01-20 13:02:23-04”,
},
{…},
]
Photogalleries
Description
Photogalleries items are an object that describes a photo gallery and the images that make it up.
Here’s an example of a photogallery as defined in JSON:
{
“id” : 1,
“url” : “
“title” : “REST Technology Gallery”,
“intro” : “Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nunc enim, sagittis a, pretium venenatis, faucibus placerat, nisl. Sed porta. Aliquam id felis sit amet.”,
“author” : “Tyler Durden”,
“images” : [{
“url”: “
“title” : “REST Diagram”,
“caption” : “REpresentational State Transfer is the architecture behind El Nuevo Día’s powerful API.”,
“alt_text” : “A REpresentational State Transfer Diagram”,
},{
“url”: “
“title” : “42”,
“caption” : “Answer to Life, the Universe, and Everything.”,
“alt_text” : “Answer to Life, the Universe, and Everything.”,
},
],
“tags” : [“rest”, “programming”, “api”, “endi”, “apex”],
“pub_date” : “YYYY-MM-DD”,
}
Some notes:
- Id: The internal id (integer) of the section.
- images: an array of image JSON objects describing images in this gallery
- tags: array of string tags describing the photogallery
- pub_date: ISO 8601 formatted string with the publication date
Methods
/photogalleries/
Returns a list of the photogalleries, by default it returns the last 10 galleries sorted by date.
URL: photogalleries /
Example URL(s):