arasaac-frontend API notes

Hi everyone,

I develop a Wordpress plugin for a German public authority which allows to configure and download pictograms similar to your site. Therefore I had some fun with the API and thought I share my findings with you to improve this great project even further. If this is not the appropriate place, please move the issue or give me a hint. The following list is work in progress and not ordered or something. Just a few findings, or thoughts.

for easier API changes, a version would be great (e.g. /api/v1/)
in general the API documentation should include descriptions of every response field
/pictograms/{locale}/{idPictogram} is responding with non-translated keywords. If I use /pictograms/{idPictogram}/languages/{languages} I can see that there are translated keywords.
there is no documentation how I can use the endpoint /pictograms/{idPictogram}/languages/{languages} for multiple languages. I have to try it with the example.
/pictograms/{idPictogram} only allows to get a resolution of 500px or 2500px. With https://static.arasaac.org/pictograms/2340/2340_300.png I can also get images with 300px which is great for search results.
/pictograms/all/{locale} is a crazy endpoint, because it just takes too long and it's too much data. Some pagination would be great.
/pictograms/{locale}/search/{searchText} and /pictograms/{locale}/new/{numItems} (in general all search like endpoins) should have the same response structure. This would make development easier.
Maybe I don't know enough about the field, but what is the purpose of the schematic, sex, and violence field?
Is there any way to get the audio from arasaac.org? Would be great if this could be included in the API.
It would also be great if there would be a license or copyright/author field in the response, because this would ensure that we are always showing the correct license. Even if currently all pictograms are licensed the same, this could maybe change in the future.
All pictograms are looking like they are vector graphics, therefore it would be nice if svg's or something else could be exposed.

I hope that's not too much at once :wink:

In case you are interested, what the WP plugin looks like (I will open another issue if the plugin is released):

I changed the organisation of the configuration options, since I believe related options should be grouped. With the great API it was also possible to hide all parameters which are not available.

Jun 13 '21 08:06 sualko

Sorry for the delay, I've just realized about the issue. I'm pretty busy with other stuff so I'll answer you next week. Nice plugin!

Jun 18 '21 13:06 juanda99

for easier API changes, a version would be great (e.g. /api/v1/)

We will try to implement versioning once we release the first stable version.

in general, the API documentation should include descriptions of every response field

We will try to improve docs once we release the first stable version.

/pictograms/{locale}/{idPictogram} is responding with non-translated keywords. If I use /pictograms/{idPictogram}/languages/{languages} I can see that there are translated keywords.

As people are using our API in its current state this failure is important to us. Could you provide us a failure example?

there is no documentation how I can use the endpoint /pictograms/{idPictogram}/languages/{languages} for multiple languages. I have to try it with the example.

Obtain pictogram data based on its key (idPictogram) for several languages. The pictogram image url can be generated based on pictogram key value and the desired resolution (300px, 500px or 2500px). For example https://static.arasaac.org/pictograms/2340/2340_2500.png for pictogram with key 2350 and resolution 2500px.

Any suggestion on how to improve the docs here? We would like it to be as minimal as possible.

/pictograms/{idPictogram} only allows to get a resolution of 500px or 2500px. With https://static.arasaac.org/pictograms/2340/2340_300.png I can also get images with 300px which is great for search results.

We generate pictogram files (png) from svg files. As this is quite an intense CPU task, we have already generated all basic PNG files in resolutionx: 300x300px, 500x500px and 2500x2500px. However, there are some variations in pictograms: black and white, plural, border, the skin where applied, and its combinations... They are not generated in 300x300px as we didn't need them, as we make pictogram variations using the pictogram editor, and in that case, we use 500x500px resolution by default.

Providing 300x300px in this API endpoint would mean that we would have to already generate all those files. However, image files are pretty optimized and I think you could use 500x500px if needed.

/pictograms/all/{locale} is a crazy endpoint, because it just takes too long and it's too much data. Some pagination would be great.

You're right, we should implement pagination as an option here, and also in other endpoints.

/pictograms/{locale}/search/{searchText} and /pictograms/{locale}/new/{numItems} (in general all search like endpoins) should have the same response structure. This would make development easier.

Could you provide an example. Using the endpoints you tell me the differente I see it's just in the order of the fields, but this is a MongoDB issue.

Maybe I don't know enough about the field, but what is the purpose of the schematic, sex, and violence field?

Sex and violence express that somehow the pictogram is related to them. By default, we use it to blur those pictograms in searches by default.

Is there any way to get the audio from arasaac.org? Would be great if this could be included in the API. locutions are related to keywords, and can be retrieved from this endpoint: https://static.arasaac.org/locutions/{language}/{keyword}.mp3

Not all pictogram keywords have locution associated, you should check hasLocution field. See for example this pitogram data for 'es' language:

{
   "_id": 37440,
  "schematic": false,
  "sex": false,
  "violence": false,
  "aac": false,
  "aacColor": false,
  "skin": true,
  "hair": true,
  "downloads": 0,
  "categories": [
    "group",
    "adult"
  ],
  "synsets": [
    "02553648-s",
    "05905605-n"
  ],
  "tags": [
  "person",
  "group",
  "adult"
],
"keywords": [
  {
    "keyword": "personas con autismo",
    "hasLocution": true,
    "type": 2
  }
],
"created": "2021-03-16T16:03:24.109Z",
"lastUpdated": "2021-03-18T10:58:55.069Z"
}

In the previous case, you could get the locution from https://static.arasaac.org/locutions/es/personas%20con%20autismo.mp3

It would also be great if there would be a license or copyright/author field in the response because this would ensure that we are always showing the correct license. Even if currently all pictograms are licensed the same, this could maybe change in the future.

We'll think about it, maybe a new endpoint just for the license. Not inside the responses as it would alter the response as it is right now with all the inconvenience.

All pictograms are looking like they are vector graphics, therefore it would be nice if SVG's or something else could be exposed. SVG's can't be exposed to comply with the agreement with our main pictogram designer.

Jun 22 '21 10:06 juanda99

Thanks for your answer and the helpful information.

We will try to implement versioning once we release the first stable version.

As you wrote "As people are using our API" and "it would alter the response as it is right now with all the inconvenience", it seams the version field should be introduced as soon as possible :wink:

Could you provide us a failure example?

I thought I verified this shortly before I wrote the issue, but I can't reproduce this anymore.

Any suggestion on how to improve the docs here?

Usually you have a list of all parameters with a description of it. Therefore something like "comma separated list of ISO 639-1 language identifiers" should work for this field.

However, image files are pretty optimized and I think you could use 500x500px if needed.

If I download pictogram 2340 with 500px it's 14kb large. With 300px it's only 7.4kb. If you display quite a few in your result view, it's a quite a difference. I don't need configuration options for these previews, but since there is no documentation if the https://static.arasaac.org/ urls are also an public API, I tried to avoid them. Maybe it's a good idea to make it more clear that this is also an api which could be used (with version identifier :wink:).

Could you provide an example. Using the endpoints you tell me the differente

I guess I'm getting crazy. I can't reproduce this either. Maybe I messed up keywords, tags and categories, since they are pretty rare in the german endpoints. Would also be nice if there would be a description of those fields, because the difference is not clear to me.

I see it's just in the order of the fields

JSON doesn't have any order, so this is no issue.

In the previous case, you could get the locution from

Would be great if this could be added to the documentation as well. But thanks for the information anyway. Can you tell me want the type field means?

Not inside the responses as it would alter the response as it is right now with all the inconvenience.

Which inconvenience? That should not affect any client.

Jun 22 '21 14:06 sualko