[wp-meta] [Making WordPress.org] #3474: Introduce `serve-happy` API endpoint

[Making WordPress.org]

#3474: Introduce `serve-happy` API endpoint
--------------------------------------+-----------------------
 Reporter:  flixos90                  |       Owner:  dd32
     Type:  task                      |      Status:  accepted
 Priority:  normal                    |   Milestone:
Component:  API                       |  Resolution:
 Keywords:  has-patch has-unit-tests  |
--------------------------------------+-----------------------

Comment (by flixos90):

 Replying to [comment:3 dd32]:
 > Returning `latest_php` probably isn't going to be useful to the
 implementation, nor actually be updated as often as PHP releases are made,
 so it's probably worth dropping that field entirely. BrowseHappy the
 website IIRC pulls the data from another source, which I don't think we'd
 want to implement in an API.

 Agreed, I can see the maintenance cost for that being too high for now,
 especially since it's not absolutely necessary.

 > Can we cache the API endpoint responses based on the `REQUEST_URI`
 alone? (If possible, reliance upon `$_POST` and `$_SERVER` vars means
 caching isn't really viable) At present it appears as such.

 Right now, the code uses `$_REQUEST` to get the parameters passed
 (`php_version`). WordPress typically has used POST requests for all the
 APIs afaik, but we could also use GET requests for this one instead, like
 `api.wordpress.org/core/serve-happy/1.0/?php_version=5.3`. Should we
 change the code so that it checks `$_GET` instead of `$_REQUEST`?
 Regarding `$_SERVER`, that is only used to detect the protocol.

 > How is it planned for the `upgrade_url` parameter passed to be host-
 specific? What data would be used?

 This is currently unknown. Maybe the IP address could be used. I thought
 it may be future-proof to include this field and also support it in core.
 This would mean whenever we get there, we don't need to wait for a core
 update. But since none of us has concrete ideas yet, we may also get rid
 of it.

 > Including the URL to `https://wordpress.org/support/upgrade-php/` seems
 like a worthwhile idea at first, although having it hard-coded in core
 would allow for locales to translate it into their own languages - which
 is far more important than it being included in the API.

 I thought about this too. I think we could support a `locale` parameter
 being passed (in the same way as the `php_version` parameter). Then this
 could return the correct URL. There's benefits and downsides to the API
 approach: The advantage would be that we can simply change the URL if it
 changes (which it may in the future, per recent discussions). The
 disadvantage is that it's probably more time-consuming to change URLs for
 locales in the codebase than in a translation string.

 > The `'upgrade'` flag isn't whether it needs upgrading, but if
 WordPress.org believes it's `out-of-date`. Calling it `upgrade` seems like
 a misnomer, It's not "Oh you're running 7.0.1, so you need to upgrade to
 7.0.27".
 > Two options I thought of while looking at it:
 > 1. Combine to single field, `status` => `out_of_date,
 no_security_updates, ok, latest` (`ok` is a bit of a random 'status' here,
 `latest` could be combined into it too)
 > 1. Rename to more verbose flags such as (for PHP 5.2) `out_of_date` =>
 `true` & `receiving_security_updates` => `false`

 That makes sense. I prefer the first approach, with a single `status`
 field. I think we don't need `latest`, particularly as it would require us
 to keep up with the latest PHP version available (see above). Maybe there
 could be another status like `up_to_date` for when the version is >=
 WordPress' recommended PHP version (that name is probably not good
 though). That would leave us with 4 statuses. But I don't have a strong
 opinion on this, we could also just have three (only `ok` as "good"
 status).

 > I think we're okay to assume that PHP will retain it's [http://php.net
 /supported-versions.php supported versions security deprecation] schedule
 for 7.x, but I question if it'll stay that way come `8.0`, having a
 `insecure_php <= 5.6` might not work too good in a far distant future, one
 we can cross when we get there (and lets ignore that Dec 3rd -> 31st
 window where 5.6 gets updates, but 7.0 doesn't :) )

 Good point. I'm not sure whether we should change behavior for that, but
 we could consider not including these version numbers in the API
 responses. It would however be less transparent to the client then.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/3474#comment:4>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org