List Libraries API Not Working

[sidwarkd]

Bug

Expected behavior

Documented query string parameters should affect returned results.

Observed behavior

Passing different sort param values returns the exact same JSON.

Steps to reproduce

I'm trying to use the Cloud API to stay on top of new community libraries as they become available and have found some confusing behavior. For example, I'd like to run a query that returns the 5 most recently created libraries so I run the following:

curl https://api.particle.io/v1/libraries?scope=all&sort=-created&limit=5&access_token=[MY TOKEN]

That returns libraries like HttpClient which obviously isn't a newly created library. But the other interesting part is that that command returns exactly the same result set as the following 3 commands:

sort=created curl https://api.particle.io/v1/libraries?scope=all&sort=created&limit=5&access_token=[MY TOKEN]

sort=-published curl https://api.particle.io/v1/libraries?scope=all&sort=-published&limit=5&access_token=[MY TOKEN]

sort=published curl https://api.particle.io/v1/libraries?scope=all&sort=published&limit=5&access_token=[MY TOKEN]

After playing with it for about an hour I came up with a list of questions that I didn't find answers to in the documentation and was hoping somebody from the team could answer.

1. Is there a query that would return the most recently created public libraries?
2. What is the order of operations of the query string params. Does limit happen before sort or sort before limit or does it depend on their order in the query string?
3. There is a page param but how does one know how many possible pages there are if the limit param defaults to 10 and has a max value of 100?
4. Why doesn't changing the sort param between ascending/descending seem to effect the output?
5. Does the sort param for published mean when it was most recently published or originally published? I assume most recently published as originally published should just be the created option.
6. Continuing from question 5, what is the difference between sorting by published and updated?
7. Is the ascending/descending sort functionality working and, if so, what am I doing wrong in the queries above?

This is the output I get for all of the above API calls.

{
  "data":[
    {
      "type":"libraries",
      "id":"coap",
      "links":{
        "download":"https://library-archives.particle.io/libraries/coap/coap-0.2.2.tar.gz"
      },
      "attributes":{
        "name":"coap",
        "version":"0.2.2",
        "installs":20,
        "license":"MIT",
        "author":"hirotakaster",
        "url":"https://github.com/hirotakaster/coap",
        "repository":"https://github.com/hirotakaster/coap.git",
        "architectures":[

        ],
        "visibility":"public",
        "mine":false
      }
    },
    {
      "type":"libraries",
      "id":"Adafruit_AM2315",
      "links":{
        "download":"https://library-archives.particle.io/libraries/Adafruit_AM2315/Adafruit_AM2315-1.0.1.tar.gz"
      },
      "attributes":{
        "name":"Adafruit_AM2315",
        "version":"1.0.1",
        "installs":17,
        "license":"BSD",
        "author":"Limor Fried/Ladyada",
        "sentence":"This is a library for the AM2315 Humidity + Temp sensor",
        "url":"https://github.com/tripzero/adafruit_am2315",
        "repository":"https://github.com/tripzero/adafruit_am2315.git",
        "architectures":[

        ],
        "visibility":"public",
        "mine":false
      }
    },
    {
      "type":"libraries",
      "id":"FirebaseArduino",
      "links":{
        "download":"https://library-archives.particle.io/libraries/FirebaseArduino/FirebaseArduino-0.0.1.tar.gz"
      },
      "attributes":{
        "name":"FirebaseArduino",
        "version":"0.0.1",
        "author":"Firebase",
        "maintainer":"Firebase",
        "sentence":"Library for communicating with Firebase.",
        "paragraph":"This library simplifies the process of communicating with Firebase. It hides the complexity of authentication and json parsing.",
        "category":"Communication",
        "url":"https://github.com/googlesamples/firebase-arduino",
        "architectures":[
          "esp8266"
        ],
        "visibility":"public",
        "mine":false
      }
    },
    {
      "type":"libraries",
      "id":"FRAM",
      "links":{
        "download":"https://library-archives.particle.io/libraries/FRAM/FRAM-1.0.1.tar.gz"
      },
      "attributes":{
        "name":"FRAM",
        "version":"1.0.1",
        "installs":13,
        "license":"GPLv3",
        "author":"Paul Kourany, Kenneth Lim",
        "sentence":"FRAM library for Particle.",
        "url":"https://github.com/enablersg/fram-lib",
        "repository":"https://github.com/enablersg/fram-lib.git",
        "architectures":[

        ],
        "visibility":"public",
        "mine":false
      }
    },
    {
      "type":"libraries",
      "id":"HttpClient",
      "links":{
        "download":"https://library-archives.particle.io/libraries/HttpClient/HttpClient-0.0.5.tar.gz"
      },
      "attributes":{
        "name":"HttpClient",
        "version":"0.0.5",
        "installs":5280,
        "license":"MIT",
        "author":"Nils Mattisson <nils.mattisson@gmail.com>",
        "sentence":"A work in progress Http Client Library for the Spark Core and Arduino.",
        "url":"https://github.com/nmattisson/httpclient",
        "repository":"https://github.com/nmattisson/httpclient.git",
        "architectures":[

        ],
        "visibility":"public",
        "mine":false
      }
    }
  ]
}

[monkbroc]

The created and published sort parameters are indeed broken right now. Thanks for the report.

1. Is there a query that would return the most recently created public libraries?

You're doing it right. It's a bug.

2. What is the order of operations of the query string params. Does limit happen before sort or sort before limit or does it depend on their order in the query string?

Always sort first, then limit.

3. There is a page param but how does one know how many possible pages there are if the limit param defaults to 10 and has a max value of 100?

It's not a great answer but we have not added the pagination metadata to the response yet. The pagination links would appear in the links response key. See http://jsonapi.org/format/#fetching-pagination

4. Why doesn't changing the sort param between ascending/descending seem to effect the output?

The sorted database fields used the wrong name.

5. Does the sort param for published mean when it was most recently published or originally published? I assume most recently published as originally published should just be the created option.

Published means most recently published.

6. Continuing from question 5, what is the difference between sorting by published and updated?

Publishing is done in 2 steps: uploading a private version and publishing it to the public. Updated is the date when the library version was uploaded as a private version. Published is when the version was made available to the public. I'm thinking right now it doesn't add much value to have both.

7. Is the ascending/descending sort functionality working and, if so, what am I doing wrong in the queries above?

It's not working, sorry.

Other than fixing the sorting bug, do you have other feedback for the library API?

[sidwarkd]

Thanks for the super quick response @monkbroc. I think that's all the feedback I have for now. I love the idea of being able to query this data to keep abreast of the library ecosystem. Thanks for answering all the questions and I'll keep an eye on this issue to know when to try my queries again.