View source for Module:Cite iucn/doc

<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
{{High-use}}

== Usage ==

<code><nowiki>{{</nowiki>#invoke:{{BASEPAGENAME}}|cite}}</code> – for {{tlx|cite iucn}}

<code><nowiki>{{</nowiki>#invoke:{{BASEPAGENAME}}|make_cite_iucn}}</code> – for {{tlx|make cite iucn}}

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>

==Background information==

===Old-style and new-style IUCN urls===

Until late 2018, the IUCN assessments used urls of form 

:<code><nowiki> http://www.iucnredlist.org/details/15955/0</nowiki></code>
:where 15955 is the taxon ID and the “0” suffix indicates a global assessment (other single digit numbers code for various regional assessments).

From around September 2018, the IUCN switched to a new format for the url, of the form

:<code><nowiki> https://www.iucnredlist.org/species/15955/50659951</nowiki></code>
:where the 15955 is the taxon ID and a unique suffix identies a version of an assessment. This left all Wikipedia links to IUCN assesssments as dead links. 

Shortly afterwards the IUCN produced a backup of the old system with links of the form

:<code><nowiki> http://oldredlist.iucnredlist.org/details/15955/0</nowiki></code>
: which uses an old-style url form on the oldredlist subdomain. Many citations were switched over to this url. However, this  subdomain was shut down near the end of 2019, leaving many dead links generating [http://oldredlist.iucnredlist.org/details/15955/0 502 Bad Gateway] errors.

===Current IUCN citations===

A typical IUCN citation, as given on their assessment pages, is now of the form:

:Goodrich, J., Lynam, A., Miquelle, D., Wibisono, H., Kawanishi, K., Pattanavibool, A., Htun, S., Tempa, T., Karki, J., Jhala, Y. & Karanth, U. 2015. ''Panthera tigris''. ''The IUCN Red List of Threatened Species'' 2015: e.T15955A50659951. https://dx.doi.org/10.2305/IUCN.UK.2015-2.RLTS.T15955A50659951.en. Downloaded on 19 December 2019.
:where the electronic page number <code>e.T15955A50659951</code> contains the taxon ID (between the T and A) and the assessment ID (after the A). These two identifying numbers are also contained in the doi.

When there is an amendment to an assessment, a new assessment number is assigned, which causes a change in the electronic page number and the url of the page. 

The behaviour of the doi is unusual. A new assessment does not cause a new doi, it retains the original assessment number. If this is used by a template to construct a url, it will be to the original version of the assessment. However, if the url of the doi is followed, the IUCN doi resolver redirects to the latest assessment. The target of the doi has changed to the revised version of the IUCN assessment. Thus if the template uses the doi url the linked page will change from the one seen by the editor who added the citation.

Therefore this module will create a url with the following order of precedence:
# Use the electronic page number set by the {{para|page}} parameter to generate the url.
# Use the {{para|id}} to generate the url if it is of the two new-style two part form, i.e. <code>TAXON_ID/ASSESSMENT_ID</code> (e.g. <code>15955/50659951</code>)
# Use the {{para|doi}} parameter to generate the url. This is last choice because it uses the number of the original  assessment even when the assessment has been amended.
When none of the above options are available, and when {{para|url}} has the old form, this module will change the scheme from <code>http://</code> to <code>https://</code> in an attempt to make a working link (see next section).

===Legacy issue with old-style urls===

There is still a legacy issue with old-style IUCN urls, which are still used in many Wikipedia citations.

Some months after the change to the new-style urls, the IUCN introduced redirects for the old-style urls that link to the appropriate pages addressed by the new style url. In most cases these redirects will work. So the oldstyle url for the tiger <code><nowiki>https://www.iucnredlist.org/details/15955/0</nowiki></code> correctly links to the assessment at <code><nowiki>https://www.iucnredlist.org/species/15955/50659951</nowiki></code> (see [https://www.iucnredlist.org/details/15955/0 tiger]). 

However, not all assessments redirect. For instance, the oldstyle url for the Bengal mud eel <code><nowiki> http://www.iucnredlist.org/details/166410/0</nowiki></code> links to the home page (see [http://www.iucnredlist.org/details/166410/0 Bengal mud eel]).

This failure of some old style url to be redirected is unexpected, as the redirect function of the IUCN API does link to the correct page. A url of the form 
:<code><nowiki>https://apiv3.iucnredlist.org/api/v3/taxonredirect/166410 </nowiki></code>
: will link to the correct page, even in cases where the automatic redirect faile, e.g. the [https://apiv3.iucnredlist.org/api/v3/taxonredirect/166410 Bengal mud eel]. 

However, redirects are not available when the taxon id has been replaced and an error in JSON format is returned (e.g. for [https://apiv3.iucnredlist.org/api/v3/taxonredirect/149100 house sparrow]).

===New taxon IDs===

There is another case where the old style urls gives dead links, when the taxon ID has changed. For instance, the Italian sparrow was split off from the house sparrow as a new species and both assigned new taxon IDs. This left any old style urls to the original assessment as dead links.

* Old-style url <code><nowiki>http://www.iucnredlist.org/details/149100/0</nowiki></code> for [http://www.iucnredlist.org/details/149100/0 house sparrow] (dead link on old taxon id <code>149100</code>)
* New-style url <code><nowiki>https://www.iucnredlist.org/species/103818789/155522130</nowiki></code> for [https://www.iucnredlist.org/species/103818789/155522130 house sparrow] (''Passer domesticus''), using new taxon id and assessment number <code>103818789/155522130</code>.
* New-style url <code><nowiki>https://www.iucnredlist.org/species/103819014/132196181</nowiki></code> for [https://www.iucnredlist.org/species/103819014/132196181 Italian sparrow] (''Passer italiae''), using new taxon id and assessment number <code>103819014/132196181</code>.

In this case there is no action the template/module can take to resolve the issue. Active intervention of an editor is required.