Skip to content

Latest commit

 

History

History
403 lines (289 loc) · 20 KB

README.md

File metadata and controls

403 lines (289 loc) · 20 KB
Raw

ko-fi

uDRAE-sdk

Con uDRAE-sdk podrás acceder fácilmente a la API del DRAE.

Tabla de contenidos

  1. Qué es y para qué sirve uDRAE-sdk
  2. Llamadas a la API y modelos de respuestas
    1. Anagrama
    2. Comienza con
    3. Contiene
    4. Termina en
    5. Búsqueda exacta
    6. Búsqueda definición por ID
    7. Búsqueda de cabecera por ID
    8. Búsqueda de IDs encontradas en la búsqueda de una palabra
    9. Búsqueda de palabras que contienen unos carácteres
    10. Palabra aleatoria
    11. Búsqueda de palabras
    12. Palabra del día
  3. Uso del SDK
    1. Obteniendo instancia de UDRAEInteractor
    2. Configurando UDRAEConfig
    3. Realizando una llamada a la API
  4. Añadir uDRAE-sdk a tu proyecto
    1. Añadiendo repositorio de jitpack
    2. Añadiendo depencencia mediante gradle
  5. Información adicional
    1. Motivaciones
    2. ¿Existe alguna alternativa en estos momentos a la aplicación oficial del DRAE?
    3. Quiero usar la API del DRAE fuera de Android, ¿qué puedo hacer?

Qué es y para qué sirve uDRAE-sdk

uDRAE-sdk (unofficial DRAE-sdk) es un conjunto de métodos que permite acceder a la API del DRAE.

En sus entrañas se encuentra Retrofit, por lo que si ya has trabajado con esta librería no tendrás ningún problema en entender el funcionamiento de uDRAE-sdk, puesto que utiliza sus Callbacks.

Llamadas a la API y modelos de respuestas

En este apartado se listan las llamadas realizadas a la API junto con su respuesta y el POJO utilizado en uDRAE-sdk.

Si entráis en cada modelo podréis observar qué significa cada atributo.

Anagrama

Llamada GET: https://dle.rae.es/data/anagram?w={word}

Descripción: Esta llamada permite obtener una lista de palabras que son anagramas de la proporcionada.

Respuesta (word = amor):

{
    "approx":0,
    "res":[
        {"word":"Roma", "header":"Roma.", "id":"WdJDhRZ"},
        {"word":"amor", "header":"amor.", "id":"2PGmlay"},
        {"word":"armo", "header":"armar.", "id":"3aoPllh"},
        ...
    ]
}

Modelo usado: AnagramResponse

Método para realizar la llamada: getAnagrams(String word, Callback<AnagramResponse> anagramResponseCallback)

Comienza con

Llamada GET: https://dle.rae.es/data/search?w={wordFragment}&m=31&f=1&t=200

Descripción: Esta llamada permite obtener una lista de palabras que comienzan con los caracteres proporcionados.

Respuesta (wordFragment = hol):

{
    "approx":0,
    "res":[
        {"header":"hola.", "id":"KYtLWBc", "grp":0},
        {"header":"holán.", "id":"KYujRuK", "grp":1},
        {"header":"holanda.", "id":"KYwHQ7M", "grp":2},
        {"header":"holandés, sa.", "id":"KYwyn6b", "grp":3},
        ...
    ]
}

Modelo usado: BaseResponse

Método para realizar la llamada: getWordsStartingWith(String wordFragment, Callback<BaseResponse> startsWithResponseCallback)

Contiene

Llamada GET: https://dle.rae.es/data/search?w={wordFragment}&m=33&f=1&t=200

Descripción: Esta llamada permite obtener una lista de palabras que contienen los caracteres proporcionados.

Respuesta (wordFragment = aro):

{
    "approx":0,
    "res":[
        {"header":"ácaro.", "id":"0IxSVOR", "grp":0},
        {"header":"acaronar.", "id":"0IyzEHW", "grp":1},
        {"header":"acharolado, da.", "id":"0QBXF9L", "grp":2},
        {"header":"acharolar.", "id":"0QC3gFz", "grp":3},
        {"header":"aerofaro.", "id":"0tpHjYd", "grp":4},
        {"header":"afarolado, da.", "id":"0vj7Xt1", "grp":5},
        ...
    ]
}

Modelo usado: BaseResponse

Método para realizar la llamada: getWordsContaining(String wordFragment, Callback<BaseResponse> containsResponseCallback)

Termina en

Llamada GET: https://dle.rae.es/data/search?w={wordFragment}&m=32&f=1&t=200

Descripción: Esta llamada permite obtener una lista de palabras terminadas con los caracteres proporcionados.

Respuesta (wordFragment = otor):

{
    "approx":0,
    "res":[
        {"header":"aeromotor.", "id":"0uNgCWY", "grp":0},
        {"header":"automotor, ra.", "id":"4TjvnOL", "grp":1},
        {"header":"bimotor.", "id":"5XG64Xm", "grp":2},
        {"header":"botor.", "id":"5zsvMD4", "grp":3},
        ...
    ]
}                                                          

Modelo usado: BaseResponse

Método para realizar la llamada: getWordsEndingWith(String wordFragment, Callback<BaseResponse> endsWithResponseCallback)

Búsqueda exacta

Llamada GET: https://dle.rae.es/data/search?w={word}&m=30

Descripción: Esta llamada permite obtener la información de una palabra en concreto.

Respuesta (word = libertad):

{
    "approx":0,
    "res":[
        {"header":"libertad.", "id":"NEeAr5C", "grp":0}
    ]
}

Modelo usado: BaseResponse

Método para realizar la llamada: getExactWord(String word, Callback<BaseResponse> exactResponseCallback)

Buscar definición por ID

Llamada GET: https://dle.rae.es/data/fetch?id={id}

Descripción: Esta llamada permite obtener la definición de la palabra representada por la ID proporcionada.

Respuesta (id = NEeAr5C):

<article id="NEeAr5C">
<header class="f">libertad.</header>
<p class="n2">Del <abbr title="latín">lat.</abbr> <em>libertas, -ātis.</em></p>
<p class="j" id="Jb6hv1z">1. <abbr class="d" title="nombre femenino">f.</abbr> <mark data-id="HTxyZDZ|HTy5CnJ">Facultad</mark> <mark>natural</mark> <mark>que</mark> <mark>tiene</mark> <mark>el</mark> <mark>hombre</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>obrar</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark data-id="b67JJSq|b6hEWeB|b6iKApr">una</mark> <mark>manera</mark> <mark>o</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark data-id="RLQQxGn">otra</mark>, <mark>y</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>no</mark> <mark>obrar</mark>, <mark>por</mark> <mark data-id="ESraxkH|NWnohQu|NWofhZh">lo</mark> <mark>que</mark> <mark data-id="EIVnk2C|Xe5Brrm">es</mark> <mark>responsable</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>sus</mark> <mark>actos</mark>.</p>
<p class="j" id="Jb6kgMf">2. <abbr class="g" title="nombre femenino">f.</abbr> <mark data-id="GjqhajH|GnJiqdL">Estado</mark> <mark>o</mark> <mark>condición</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>quien</mark> <mark>no</mark> <mark data-id="EIVnk2C|Xe5Brrm">es</mark> <mark>esclavo</mark>.</p>
...

Modelo usado: String (devuelve el HTML con la definición)

Método para realizar la llamada: getDefinitionById(String id, Callback<String> htmlDefinitionCallback)

Búsqueda de cabecera por ID

Llamada GET: https://dle.rae.es/data/header?id={id}

Descripción: Esta llamada permite obtener la cabecera que hace referencia a la ID proporcionada.

Respuesta (id = NEeAr5C):

{ "header":"libertad."}

Modelo usado: HeaderResponse

Método para realizar la llamada: getHeaderById(String id, Callback<HeaderResponse> headerResponseCallback)

Búsqueda de IDs encontradas en la búsqueda de una palabra

Llamada GET: https://dle.rae.es/data/ids?w={word}

Descripción: Esta llamada permite obtener las IDs de las palabras que se encuentran cuando realizamos la búsqueda de una palabra.

Respuesta (word = hola):

{ "res" : ["KYtLWBc"] }

Modelo usado: IdResponse

Método para realizar la llamada: getIdsMatchingWord(String word, Callback<IdResponse> idResponseCallback)

Búsqueda de palabras que contienen unos carácteres

Llamada GET: https://dle.rae.es/data/keys?q={query}&callback=jsonp123

Descripción: Esta llamada permite obtener una lista de palabras que empiezan con los caracteres (query) introducidos. Es muy útil por ejemplo para crear una lista de palabras sugeridas mientras el usuario va introduciendo su búsqueda.

Respuesta (query = hol):

jsonp123(["hola","holán","holanda","holandés","holandesa","holandeta","holandilla","holco","holding","holear"])

Modelo usado: ArrayList<String>

Método para realizar la llamada: getSomeMatchingWords(String word, Callback<ArrayList<String>> keysResponseCallback)

Palabra aleatoria

Llamada GET: https://dle.rae.es/data/random

Descripción: Esta llamada devuelve la definición de una palabra aleatoria.

Respuesta:

<article id="NEeAr5C">
<header class="f">libertad.</header>
<p class="n2">Del <abbr title="latín">lat.</abbr> <em>libertas, -ātis.</em></p>
<p class="j" id="Jb6hv1z">1. <abbr class="d" title="nombre femenino">f.</abbr> <mark data-id="HTxyZDZ|HTy5CnJ">Facultad</mark> <mark>natural</mark> <mark>que</mark> <mark>tiene</mark> <mark>el</mark> <mark>hombre</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>obrar</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark data-id="b67JJSq|b6hEWeB|b6iKApr">una</mark> <mark>manera</mark> <mark>o</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark data-id="RLQQxGn">otra</mark>, <mark>y</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>no</mark> <mark>obrar</mark>, <mark>por</mark> <mark data-id="ESraxkH|NWnohQu|NWofhZh">lo</mark> <mark>que</mark> <mark data-id="EIVnk2C|Xe5Brrm">es</mark> <mark>responsable</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>sus</mark> <mark>actos</mark>.</p>
<p class="j" id="Jb6kgMf">2. <abbr class="g" title="nombre femenino">f.</abbr> <mark data-id="GjqhajH|GnJiqdL">Estado</mark> <mark>o</mark> <mark>condición</mark> <mark data-id="BtDkacL|BtFYznp">de</mark> <mark>quien</mark> <mark>no</mark> <mark data-id="EIVnk2C|Xe5Brrm">es</mark> <mark>esclavo</mark>.</p>
...

Modelo usado: String (devuelve el HTML con la definición)

Método para realizar la llamada: getRandomWord(Callback<String> htmlDefinitionCallback)

Búsqueda de palabras

Llamada GET: https://dle.rae.es/data/search?w={word}

Descripción: Esta llamada devuelve una lista de palabras que coinciden con la búsqueda que se ha hecho.

Respuesta (word = amo):

{
    "approx":0,
    "res":[
        {"header":"amar.", "id":"2E4Cede", "grp":0},
        {"header":"amo, ma.", "id":"2ND9BMI", "grp":1}
    ]
}

Modelo usado: BaseResponse

Método para realizar la llamada: getWordSearchResults(String word, Callback<BaseResponse> wordSearchResultsCallback)

Palabra del día (WOTD)

Llamada GET: https://dle.rae.es/data/wotd?callback=json

Descripción: Esta llamada devuelve información sobre la palabra del día (gestionada por los servidores del DRAE).

Respuesta:

json({"header":"versus.","id":"bfyaXi1"})

Modelo usado: WOTDResponse

Método para realizar la llamada: getWordOfTheDay(Callback<WOTDResponse> wotdResponseCallback)

Uso del SDK

Evidentemente necesitas proporcionar permisos de INTERNET a tu aplicación (puedes hacerlo en AndroidManifest.xml.

<uses-permission android:name="android.permission.INTERNET" />

Obteniendo instancia de UDRAEInteractor

UDRAEInteractor udraeInteractor = new UDRAEInteractor(MainActivity.this, UDRAEConfig.getDefaultUDRAEConfig());

Configurando UDRAEConfig

Podemos utilizar la configuración por defecto de UDRAEConfig como se está haciendo en el ejemplo de arriba. La configuración por defecto presenta estos valores:

  • Duración del cacheo de las llamadas: 30 días.
  • Duración del cacheo (para casos en los que no hay internet): 180 días.
  • Tamaño de la carpeta que almacenará el caché: 10_485_760 (10 MiB).
  • Timeout de la conexión: 15 segundos.
  • Nombre de la carpeta que almacenará el caché: udrae-cache

Si quieres personalizar la configuración, puedes hacerlo así:

UDRAEConfig udraeConfig = new UDRAEConfig.Builder()
                .setCacheSize(20 * 1024 * 1024)
                .setCacheDuration(15)
                .setOfflineCacheDuration(360)
                .setCacheFolderName("custom-cache")
                .apply();

Y posteriormente pasarle esa instancia de UDRAEConfig al constructor de UDRAEInteractor.

Realizando una llamada a la API

Por ejemplo, si queremos realizar una búsqueda exacta podemos hacerlo así:

udraeInteractor.getExactWord("hola", new Callback<BaseResponse>() {
            @Override
            public void onResponse(Call<BaseResponse> call, Response<BaseResponse> response) {
                Log.d("It works!", response.body().getRes().get(0).getHeader());
            }

            @Override
            public void onFailure(Call<BaseResponse> call, Throwable t) {
                Log.e("It doesn't work. :(", t.getMessage());
            }
        });

En este ejemplo estamos obteniendo la ID del primer resultado que nos devuelve la búsqueda de la palabra hola. Después podemos usar esa ID para realizar la búsqueda de la definición por ID.

Añadir uDRAE-sdk a tu proyecto

Añadiendo repositorio de jitpack

Añade lo siguiente al build.gradle ubicado en la raíz, no el del módulo.

allprojects {
	repositories {
		...
		maven { url "https://jitpack.io" }
	}
}

Añadiendo dependencia mediante gradle

Añade lo siguiente al build.gradle de tu módulo. (Asegúrate de que la versión sea la misma que la del distintivo de arriba)

dependencies {
	...
	compile 'com.github.GrenderG:uDRAE-sdk:1.0.4'
}

Información adicional

Motivaciones

Personalmente pienso que la información que proporciona el DRAE (propiedad de la RAE) debería ser de dominio público para que cualquiera pudiera hacer uso de ella de la forma que quisiera (recordemos que la institución se financia también con dinero público) sin tener que encontrarse con la cantidad de licencias restrictivas que poseen las obras de la RAE (tan restrictivas que siendo estrictos ni los buscadores podrían indexar su contenido ni se pueden citar definiciones en trabajos académicos sin estar infringiendo su propiedad intelectual).

Basándome en mi opinión sobre lo anteriormente expuesto, he considerado hacer pública y accesible la API que utiliza la aplicación de su diccionario para así permitir a todo el mundo tener el derecho de crear sus propias apps de diccionarios o que simplemente utilicen la información que proporciona el DRAE.

¿Existe alguna alternativa en estos momentos a la aplicación oficial del DRAE?

Diccionario (por freespanish) Aunque este diccionario no utiliza este SDK es totalmente funcional y hace uso del contenido original del DRAE.
pyrae Consulta el DRAE desde tu terminal con este software hecho en Python.

¿Haces uso del SDK o de algún recurso del DRAE y quieres aparecer aquí? Abre un issue o un Pull Request con tu aplicación añadida.

Quiero usar la API del DRAE fuera de Android, ¿qué puedo hacer?

Actualmente lo único que puedes hacer es hacer uso de una llamada GET que no está protegida por ningún certificado ni autenticación.

La llamada es la siguiente:

http://dle.rae.es/srv/search?w={word}

Siendo {word} la palabra a buscar. Esta llamada nos devolverá un HTML conteniendo el resultado de nuestra búsqueda.