Page MenuHomePhabricator

Figure out at what domain the api should be hosted
Closed, ResolvedPublic

Description

Currently, the api is at recommend.wmflabs.org/api, but this will be changing with the deployment to production. This task is to come to a consensus on where it should land. We want the title to be self-explanatory, but not ambiguous.

Concerns:

  • There are community projects that do recommendations
  • Is this for all recommendations, or just article-based ones?

Initial suggestion to spark the discussion: recommendation.wikimedia.org

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 5 2016, 1:18 PM
schana triaged this task as High priority.Oct 5 2016, 1:18 PM
schana moved this task from Backlog to Next up on the Recommendation-API board.
leila added a comment.Jan 19 2017, 6:46 PM

@DarTar are we happy with recommendation.wikimedia.org as the domain for the recommender-api? If yes, we can move ahead with it.

what was the reason not to use "recommend" instead? It's a bit of a mouthful, wondering if there isn't something shorter and equally descriptive.

I think recommendations or recommender makes the most sense as far as what is being provided, whereas recommend is a bit more ambiguous as to who is performing the action. We could always abbreviate to recs, but it may hurt discoverability.

Is an option to integrate it in REST api considered? At least the 'related articles' recommendation can fit in the rest API really well replacing that backed for the related endpoint.

I would discourage the use of recommendation.wm.org as we are trying to minimise the number of sub-domains (cf. T133001) specific services are using and bring most of the APIs under the unified /api/rest_v1/ endpoint. This makes the recommendation API more easily discoverable by clients and provides them with documentation. The logic here is that the user shouldn't be concerned by which service is providing which chuck of the overall functionality, while at the same time having an overview of everything that is provided by the API in general. Additionally, not tying yourself to a specific sub-domain allows us to keep the same API while swapping the back-end performing the task transparently from the client's perspective.

@Pchelolo @mobrovac I think our primary concern is in having a well-known location to surface the different recommendation types. There is no problem AFAIK with having that be under /api/rest_v1, provided there's some namespace (or functionally equivalent space) where all the recommendation types can be discovered together.

@schana There's a concept of tags in the docs, so you can group related endpoints together. Here's an example for mobile-related endpoints: https://en.wikipedia.org/api/rest_v1/#/Mobile

This is pending based on T157588 and T157589

leila added a comment.Apr 13 2017, 4:13 PM

@schana please go ahead with finding a solution for this. We don't need to wait for product lead and tech lead for this, imo.

leila moved this task from Backlog to Next up on the Recommendation-API board.Apr 13 2017, 4:13 PM

I think we're all happy with these APIs living under the /api/rest_v1/ endpoint and having a tag to group them together. @mobrovac @Pchelolo any objections?

I think we're all happy with these APIs living under the /api/rest_v1/ endpoint and having a tag to group them together. @mobrovac @Pchelolo any objections?

@schana Nope, that was exactly the intention.

+1. Now we have to bike-shed on the layout :)

+1. Now we have to bike-shed on the layout :)

T163210 created

leila closed this task as Resolved.Apr 20 2017, 5:06 PM