search

juanda99 / arasaac-frontend

New website for arasaac.org
MIT License
14 stars 4 forks source link

API notes #103

Open sualko opened 3 years ago

sualko commented 3 years ago

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.

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):

image

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.

image

juanda99 commented 3 years ago

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!

juanda99 commented 3 years ago

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

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

As people are using our API in its current state this failure is important to us. Could you provide us a failure 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.

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.

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

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.

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.

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

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.

sualko commented 3 years ago

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.