Finalize the API

[omelnyk]

People use the API for mobile apps, so making changes to it progressively is painful. We'd better get it nice and fluffy from the start.

Generic remarks:

• [ ] get rid of the redundant "api" suffix (eg. hwfindnearbycityapi) in API call names
• [ ] unnest the result set from the the query property. It was probably copy-pasted to resemble MediaWiki's query API call's result set, and applies to all Hitchwiki's custom calls:

  {
  "query": {
      "ratings": [
          ...
      ],
      "distribution": {
          ....
      }
  }
  }

  should become:

  {
  "ratings": [
      ...
  ],
  "distribution": {
      ....
  }
  }

hwspotidapi:

• [ ] change its confusing name to eg. hwgetspot
• [ ] get rid of redundant _ratinguser field? (there's ratings array already)
• [ ] make all property names lowercase
• [ ] fields that aren't meant to be arrays (eg. country) shouldn't be returned as such
• [ ] make user_id parameter optional / get rid of it;

...more API calls to be added here (feel free)

[amaury1093]

hwspotidapi:

• The Description field returns some HTML, e.g. <div style=\"display:none\">\n<p><br />\n</p><p><br />\n57\u00b0 4' 41\", 22\u00b0 17' 34\"\n<a href=\"/en/Latvia\" title=\"Latvia\">Latvia</a>\n</p>\n</div>\n<p>To Sabile, Talsi, Tukums, Riga. Just wait here for the car you need. Do not walk for a better position, because you will walk around 10-12 km\n</p> with info about GPS location and country. It would be good to return the description only, GPS and country are in other fields.

• Idem for comments.

• [BUG]: http://beta.hitchwiki.org/en/Special:ApiSandbox#action=hwspotidapi&format=json&page_id=10023&properties=Cities%2CCountry%2CCardinalDirection&user_id=0. It's not a spot, but a wiki page. The description is filled with the content of the wiki page.

[simison]

get rid of the redundant "api" suffix (eg. hwfindnearbycityapi) in API call names

Makes sense. 👍

unnest the result set from the the query property. It was probably copy-pasted to resemble MediaWiki's query API call's result set, and applies to all Hitchwiki's custom calls:

{
    "query": {
        "ratings": [
            ...
        ],
        "distribution": {
            ....
        }
    }
}

I recon this is default MW API stuff. There could be also debug info, errors and warnings there. See e.g.: https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&causes_warning=1&format=jsonfm

FYI also this: https://www.mediawiki.org/wiki/API:JSON_version_2

get rid of redundant rating_user field? (there's ratings array already)

Keeping. It holds currently authenticated user's rating of that spot.

make all property names lowercase

:thumbsup:

fields that aren't meant to be arrays (eg. country) shouldn't be returned as such

Are you sure it's not meant to be an array? Should be defined here: https://github.com/Hitchwiki/hitchwiki/tree/master/scripts/pages

make user_id parameter optional / get rid of it;

:thumbsup: Totally. I'm getting rid of this already, e.g.: https://github.com/Hitchwiki/HWRatings-extension/blob/master/api/HWAvgRatingApi.php#L23

[simison]

The Description field returns some HTML, e.g

Totally, should be removed. No idea how it ends up there. I also wonder if there's a way to get descriptions (and comments) as raw wiki format instead of Html.

<div style=\"display:none\"> hack might indicate that we were already looking into it, tho, but didn't solve it yet perfectly, dunno.

Here where it gets pulled out from the DB: https://github.com/Hitchwiki/HWMap-extension/blob/master/api/HWSpotIdApi.php#L43-L57

[amaury1093]

hwmapapi:

• [BUG] average_ratings are not populated. E.g. http://beta.hitchwiki.org/en/Special:ApiSandbox#action=hwmapapi&format=json&NElat=49&NElon=50&SWlat=0&SWlon=10&utf8=1

[omelnyk]

The Description field returns some HTML, e.g

Totally, should be removed. No idea how it ends up there. I also wonder if there's a way to get descriptions (and comments) as raw wiki format instead of Html.

We should use SMW Ask API instead of parse API like we're doing now

[simison]

^ that could work.

I also renamed Location to location and it it's now just an object instead of an array of objects.

[leocarona]

make user_id parameter optional / get rid of it;

Make it optional but please don't get rid of it. We'll need to fetch spots added by the users on MyHitchhikingSpots.

[simison]

@leocarona user_id is now always gonna be based on session, so as long as user is logged in and you pass the session id with your requests, you can be sure you're getting data related to that user.

[leocarona]

@simison How to see another user's spots, though? Some ppl could find it interesting to be able to see spots added by a friend?