Referencias API

API significa "Application Programming Interface". Una API proporciona un conjunto de comandos, funciones y protocolos para facilitar la programaci´┐Żn de software. Estas funciones predefinidas simplifican la interacci´┐Żn del programador con el sistema operativo, ya que el hardware (monitor, datos en el disco duro, etc.) no tiene que ser direccionado directamente. En lo que se refiere a Internet, las APIs Web est´┐Żn a la vanguardia y tambi´┐Żn sirven como interfaz para permitir el uso de funciones existentes de terceros.

Image

API Reference

Curabitur lacinia convallis nibh, non cursus augue. Quisque id sem id lorem porttitor efficitur in quis libero. Nullam turpis ante auctor purus sed.

https://examples.com

Authentication

Ante la imparable evoluci´┐Żn de aplicaciones, frameworks, lenguajes y alternativas para facilitarnos las tareas de Desarrollo Web en diferentes ´┐Żmbitos, hablaremos a continuaci´┐Żn sobre el modelo de autenticaci´┐Żn para API REST de nuestra infraestructura. Las API REST que nuestro cloud entrega son uno de los mejores recursos actuales para cualquier desarrollador y en esta ocasi´┐Żn, queremos que conozcas mejor las caracter´┐Żsticas y el flujo de este modelo.

En el mundo de las API REST, se deben implementar flujos distintos de los habituales en cuanto a la autenticaci´┐Żn de usuarios, ya que su arquitectura nos ofrece otro tipo de recursos que los tradicionales. Por lo general, en las aplicaciones web tradicionales, se utilizan las variables de sesi´┐Żn como soporte para memorizar el usuario. Esto viene a decir que en el momento de autenticar un usuario, el servidor genera las correspondientes variables de sesi´┐Żn y en las siguientes p´┐Żginas consultadas por ese mismo cliente, es capaz de recordar al usuario.

Sin embargo, en las aplicaciones REST, esto no es posible, ya que una de las limitaciones de este sistema es que no se dispone de variables de sesi´┐Żn. Esto es debido a motivos de escalabilidad, ya que las API REST suelen estar alojadas en un cluster de servidores. La soluci´┐Żn habitual para salvar este problema es la autenticaci´┐Żn por token.

Flujo de autenticaci´┐Żn por usuario y contrase´┐Ża
El hecho de usar un token como mecanismo involucrado en la autenticaci´┐Żn no produce efectos visibles para los usuarios, ya que estos no tienen que lidiar con ´┐Żl directamente. Dicho de otra manera, todas las diferencias en el flujo son transparentes para el usuario.

Nuestro API Cloud Center trabaja de forma standarizada y por defecto con autenticaci´┐Żn de token basado en parametros querys:

Token de Suscripci´┐Żn (token-susc): Este token permite en cada llamado a la api identificar la suscripci´┐Żn del usuario.
Token de API (token-api): Este token permite identificar la key de la API que se requiere consumir.

Otros Mecanismos de Seguridad: En caso que el usuario as´┐Ż lo requiera pueda proteger sus tokens y keys utilizando diferentes mecanismos de seguridad como:
- Authentication by Header
- API EndPoint to Generate Tokens Dynamics.
- oauth2

Parametros Seguridad
  • token-susc

    Mediante el parametro token-susc el sistema debera recibir la key seteada a su suscripci´┐Żn y que se encuentra disponible en su Panel Comercial.
    Ejemplo: "token-susc":"20190d614196076fb924df8dd392c5as"

  • token-api

    Mediante el parametro token-api el sistema debera recibir la key seteada a la API que esta queriendo consumir. Dicha API puede ser solicitada desde su Panel Comercial.
    Ejemplo: "token-api":"9f9f0fe087e970b8c21c4577e1cd95af"

Errores de Autenticaci´┐Żn:
200 - OK OK.
401 - Security Security tokens not found.
401 - Security Security tokens not defined.
401 - Security Security tokens error.
409 - Unauthorized Suscription stoped.
409 - Unauthorized Api offline or discontinued.
429 - Limits Limit exceeded.

Parametros de Entrada

Mediante el metodo de llamado la API () puede recibir los siguientes parametros de entrada:

Parametros Entrada

											curl -X GET "https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID" -H "accept: application/json"
										

											import requests
											r = requests.get('https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID')
											r.json()
										

											require 'net/http'
											require 'json'

											url = 'https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID'
											uri = URI(url)
											response = Net::HTTP.get(uri)
											JSON.parse(response)
										

											$json = file_get_contents('https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID');
											echo $json;
											$obj = json_decode($json);
										

											import java.io.BufferedReader;
											import java.io.IOException;
											import java.io.InputStream;
											import java.io.InputStreamReader;
											import java.io.Reader;
											import java.net.URL;
											import java.nio.charset.Charset;

											import org.json.JSONException;
											import org.json.JSONObject;

											public class JsonReader {

											  private static String readAll(Reader rd) throws IOException {
												StringBuilder sb = new StringBuilder();
												int cp;
												while ((cp = rd.read()) != -1) {
												  sb.append((char) cp);
												}
												return sb.toString();
											  }

											  public static JSONObject readJsonFromUrl(String url) throws IOException, JSONException {
												InputStream is = new URL(url).openStream();
												try {
												  BufferedReader rd = new BufferedReader(new InputStreamReader(is, Charset.forName("UTF-8")));
												  String jsonText = readAll(rd);
												  JSONObject json = new JSONObject(jsonText);
												  return json;
												} finally {
												  is.close();
												}
											  }

											  public static void main(String[] args) throws IOException, JSONException {
												JSONObject json = readJsonFromUrl("https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID");
												System.out.println(json.toString());
												System.out.println(json.get("id"));
											  }
											}
										

											Private Function GetAPIDATA() As String
												Dim xmlHttp As Object
												Dim strTokenSusc as String
												Dim strTokenAPI as String
												Dim strUrl as String

												strTokenSusc = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
												strTokenAPI = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

												strUrl = "https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=" & strTokenSusc & "&token-api=" & strTokenAPI & "&internalid=YOUR_INTERNAL_ID"


												Set xmlHttp = CreateObject("MSXML2.XmlHttp")
												xmlHttp.Open "GET", sURL, False
												xmlHttp.send
												GetAPIDATA = xmlHttp.responseText
												Set xmlHttp = Nothing
											End Function
										

											<%
												dim url
												url = "https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID"
												Set HttpReq = Server.CreateObject("MSXML2.ServerXMLHTTP")
												HttpReq.open "GET", url, false
												HttpReq.setRequestHeader "Content-Type", "application/json"
												HttpReq.Send()
											%>
										

											using (var httpClient = new System.Net.Http.HttpClient())
											{
												var json = await httpClient.GetStringAsync("https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID");
											}
										

											var https = require('https');

											var options = {
												host: 'https://cont1-virtual1.certisend.com/web/container/api/v1/',
												path: '?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID',
												headers: {
													'Accept': 'application/json'
												}
											};
											https.get(options, function (res) {
												var json = '';

												res.on('data', function (chunk) {
													json += chunk;
												});

												res.on('end', function () {
													if (res.statusCode === 200) {
														try {
															var data = JSON.parse(json);
															// data is available here:
															console.log(json);
														} catch (e) {
															console.log('Error parsing JSON!');
														}
													} else {
														console.log('Status:', res.statusCode);
													}
												});
											}).on('error', function (err) {
												console.log('Error:', err);
											});
										

											package main

											import (
												"fmt"
												"net/http"
												"io/ioutil"
												"os"
												)

											func main() {
												response, err := http.Get("https://cont1-virtual1.certisend.com/web/container/api/v1/?token-susc=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&token-api=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&internalid=YOUR_INTERNAL_ID")
												if err != nil {
													fmt.Printf("%s", err)
													os.Exit(1)
												} else {
													defer response.Body.Close()
													contents, err := ioutil.ReadAll(response.Body)
													if err != nil {
														fmt.Printf("%s", err)
														os.Exit(1)
													}
													fmt.Printf("%s\n", string(contents))
												}
											}
										

Parametros de Salida

Una vez consumida la API y siempre y cuando la respuesta de la misma y el contro de autenticaci´┐Żn retorne un 200-OK, la misma arrojara los siguientes campos de salida en formato JSON:

ID Campo Tipo Longitud Descripci´┐Żn
Otros C´┐Żdigos HTTP
200 - OK Respuesta est´┐Żndar para peticiones correctas.
400 - Bad Request El servidor no procesar´┐Ż la solicitud, porque no puede, o no debe, debido a algo que es percibido como un error del cliente (ej: solicitud malformada, sintaxis err´┐Żnea, etc). La solicitud contiene sintaxis err´┐Żnea y no deber´┐Ża repetirse.
401 - Unauthorized Similar al 403 Forbidden, pero espec´┐Żficamente para su uso cuando la autentificaci´┐Żn es posible pero ha fallado o a´┐Żn no ha sido provista.
404 - Not Found Una petici´┐Żn fue hecha a una URI utilizando un m´┐Żtodo de solicitud no soportado por dicha URI; por ejemplo, cuando se utiliza GET en un formulario que requiere que los datos sean presentados v´┐Ża POST, o utilizando PUT en un recurso de solo lectura.
409 - Conflict Indica que la solicitud no pudo ser procesada debido a un conflicto con el estado actual del recurso que esta identifica.
429 - Too Many Requests Hay muchas conexiones desde esta direcci´┐Żn de internet.
500, 502, 503, 504 - Server Errors El servidor fall´┐Ż al completar una solicitud aparentemente v´┐Żlida.