NSL API Documentation

v1.0, June 2015 (Main documentation for the NSL API version 1.0)

1. Introduction

1.1. Australian Plant Name Index (APNI)

APNI is a database for the botanical community that deals with the names of Australian plants and their usage in the scientific literature, whether as a current name or synonym. APNI does not recommend any particular taxonomy or nomenclature. For a listing of currently accepted scientific names for the Australian vascular flora, see the Australian Plant Census (APC). Information available from APNI includes:

• Scientific plant names;

• Author details;

• Original publication details (protologue), with links to a PDF in some cases via a PDF icon

• Subsequent usage of the name in the scientific literature (in an Australian context)

• Typification details;

• An APC tick showing which, if any, concept has been accepted for the APC

• State distribution (from the Australian Plant Census (APC));

• Relevant comments and notes;

• Links to other information such as plant distributions, descriptions and images search via a picture search icon.

APNI is maintained at the Centre for Australian National Biodiversity Research with staff, resources and financial support from the Australian National Herbarium, Australian National Botanic Gardens and the Australian Biological Resources Study. The CANBR, ANBG and ABRS collaborate to further the updating and delivery of APNI and APC.

1.2. Australian Plant Census (APC)

APC is a database of the accepted scientific names for the Australian vascular flora, ferns, gymnosperms, hornworts and liverworts, both native and introduced, and lists synonyms and misapplications for these names. The APC will cover all published scientific plant names used in an Australian context in the taxonomic literature, but excludes taxa known only from cultivation in Australia. The taxonomy and nomenclature adopted for the APC are endorsed by the Council of Heads of Australasian Herbaria (CHAH).

For further information about names listed in APC, including bibliographic information, secondary references and typification, consult the Australian Plant Name Index (APNI). Alternatively, clicking on hyperlinked names in APC search results will link to the APNI data for any given name.

Information available through APC includes:

• Accepted scientific name and author abbreviation(s);

• Reference to the taxonomic and nomenclatural concept adopted for APC;

• Synonym(s) and misapplications;

• State distribution;

• Relevant comments and notes

APC is coordinated through a network of contributors, and is maintained by the Centre for Australian National Biodiversity Research with staff, resources and financial support from the Australian National Herbarium, Australian National Botanic Gardens, Australian Biological Resources Study, CHAH and State and Territory herbaria. These organisations collaborate to further the updating and delivery of APC.

1.3. National Species List (NSL)

The National Species List is a complete database covering vascular plants, mosses, fungi, animals etc. The data for the NSL is kept in disparate systems that are combined under the NSL.

The current NSL infrastructure does this via RDF web services over some semi static datasets, "but that is changing." What you see here is the start of the new NSL infrastructure that allows the separatly governed datasets to be curated by their "owners" while combining them into a live discoverable, searchable data resource with a consistent modern interface.

The new infrastructure takes the existing datasets and makes them "shards" of the NSL. Each shard will be imported separately into the new system as resources allow.

The new system incorporates an improved editing system and separate distributed search services, including linked data services.

1.3.1. What we have now

We have migrated

1. APNI and APC

2. Mosses (AusMoss)

3. Lichens (ABRS)

data into NSL "shards".

The NSL services including search and the RDF/SPARQL interfaces are available via https://biodiversity.org.au/nsl .

1.3.2. The road map

We will be adding new shards to the system as we go, with the likely priority as:

1. Fungi

2. Algae

3. Mosses

4. Lichen

5. the Australian Faunal Directory

As we add datasets, improvements to the editor and services will be required to cater for differing requirements, these changes will be incorporated based on priorities and resources.

2. Using the NSL

2.1. Searching the NSL

The current NSL service includes the APNI and APC data. APNI is a nomenclator, it includes a list of names of vascular plants and where they have been used in references. In this sense, APNI has no opinion about the name, it just states where and how it has been used in a reference.

APC is a consensus-based classification, it provides an opinion about what is the accepted name, and where the taxon sits in the classification "tree".

When you look at the NSL services page you will see the APNI and APC "products" as links in the "Navigation Bar" at the top of the page. To search APNI click the APNI link.

Open

Figure 1. The NSL Services page (APNI product)

The search page consists of a set of search forms that can be found by selecting the appropriate tab.

2.1.1. Name Search

By default when you go to the search page you are on the "Name Search" tab. This gives you a simple text box to enter a search for the name or names you are looking for.

When you type your query into the search box you will get suggestions that tell you what your query is likely to return. The system only returns the first 15 matching names in the suggestion, and will end with an ellipsis (…​) if there are more results. You can click on one of those suggestions to copy it to the search box.

The name search looks at the 'Full Name including the Author', so the system adds an automatic wild card at the end of the query to match all endings. This means that if you just enter the simple name without author you should find what you want, however it may also return more than you expect.

The query is not case sensitive.

The query is an ordered set of search terms, so viola l. will match "Viola L." and "Viola L. sect Viola."

Putting double quotes around your entire query will cause it to be matched exactly (except case). e.g. "Viola L." will match just Viola L.

You can use a % as a wild card inside the search query e.g. hakea elon% be or "hakea % var. elon% benth." to find "Hakea ceratophylla var. elongata Benth."

You can search for hybrids using the letter 'x' or a multiplication sign &mul; if you use a multiplication sign.

Under Construction

This documentation is under construction. We understand it needs extending and improving, but we thought we’d let you see what we’ve got so far.

3. Application Interfaces (APIs)

The NSL services provide a number of Application Interfaces, called APIs, to let you access the name data within.

3.1. Changes

This section lists recent changes to the API.

May 1 2016 : * Removed NSL Simple Name export and JSON representation. June 22 2016 : * Added the Export section * Added name taxon-search api end point

3.2. Linked Data

The NSL system uses a linked data service called a mapper or broker to map the URIs for a resource to a service that can provide that resource. As linked data we don’t guarantee that the same service will deliver the resource each time, but we do guarantee the object returned will be the same one associated with that URI.

The Mapper takes the URI and will issue you a '303 redirect' to a service that will provide the requested resource in the format requested.

The mapper uses content negotiation to provide you with the correct service for the resource in the format you request, e.g. HTML, JSON, XML, RDF. You must follow the 303 redirect to the service and provide the redirected service the same content type to get the correct format.

Browsers do not allow you to request a different content type (easily), and you will always get HTML back in a browser. To make it easier to demonstrate the other format, or just browse them we have provided '.format' handling in our services so you can add '.json' or '.xml' to a URL to get the desired format. The .format does not survive the 303 redirection, so you will need to add it to the redirected service URL manually.

e.g. the URL https://id.biodiversity.org.au/name/apni/70914.json redirects to https://biodiversity.org.au/nsl/services/api/name/apni/70914

As you can see below the browser gets the 303 redirect and goes there, but the browser only 'accepts' html.

Open

Figure 2. 303 redirect headers

If you now add '.json' to the redirected service URL in the browser we can force the response to JSON.

Figure 3. Forcing a JSON response using .json

3.3. Basic Resource Objects

The basic resource objects in the NSL system are representations of the underlying database objects, which in turn represent the taxonomic world. As such you will need to construct a view of the taxonomic object from these objects. Some higher level api calls perform some of this work for you to create a useful view.

The basic form of a URI to return an object from the API via a preferred link is:

3.3.1. Author

An Author (person) object represents a Name or Reference author. It’s primary purpose is to act as an identifier for an author that can be linked to another identifier such as an IPNI Author.

Currently an author of both references and names may have two Author entries because of the imported APNI data. We will be working to de-duplicate these authors over time.

e.g. https://id.biodiversity.org.au/author/apni/1441

Figure 4. Author object HTML output

Example JSON output (Names left out)

3.3.2. Instance

An instance object represents an instance of the use of a Name in a Reference (a Usage) and it relationship. There are two main Instance occurrences, 'Standalone' instances and 'Relationship' instances (see figure below).

Figure 5. Instance relationships.

An Instance is of a particular instance type. Each instance type defines a set of properties for that instance. The currently defined instance types are:

1. replaced synonym

2. basionym

3. pro parte replaced synonym

4. nomenclatural synonym

5. doubtful nomenclatural synonym

6. pro parte nomenclatural synonym

7. pro parte misapplied

8. doubtful misapplied

9. doubtful pro parte misapplied

10. taxonomic synonym

11. pro parte taxonomic synonym

12. doubtful taxonomic synonym

13. doubtful pro parte taxonomic synonym

14. synonym

15. pro parte synonym

16. doubtful synonym

17. doubtful pro parte synonym

18. isonym

19. autonym

20. trade name

21. comb. et stat. nov.

22. comb. nov.

23. comb. et nom. nov.

24. misapplied

25. nom. et stat. nov.

26. nom. nov.

27. tax. nov.

28. excluded name

29. doubtful invalid publication

30. primary reference

31. homonym

32. invalid publication

33. [n/a]

34. [unknown]

35. sens. lat.

36. common name

37. vernacular name

38. [default]

39. secondary reference

40. implicit autonym

41. orthographic variant

As you can see the instance type describes the relationship of the reference to the name.

Basic Instance object structure

e.g. https://id.biodiversity.org.au/instance/apni/481759

Figure 6. Instance object HTML output

Example Full JSON output

3.3.3. InstanceNote

Instances can have several notes associated with them. An instance Note consists of a key and a value. Current instance note keys are:

1. Neotype

2. Ex.distribution

3. APC Comment

4. EPBC Impact

5. Status

6. Under

7. Distribution

8. URL

9. Lectotype

10. Context

11. Vernacular

12. Text

13. Comment

14. Synonym

15. Type

16. APC Dist.

17. Etymology

18. EPBC Advice

19. APNI

20. Type herbarium

e.g. https://id.biodiversity.org.au/instanceNote/apni/1121197

Figure 7. Instance Note object HTML output

Example Full JSON output

3.3.4. Name

The Name object represents a name string, type, rank, and status. This object is an identifier of a name string with enough information to be able to reconstruct the name string from parts. As an identifier it links together Instances and Authors.

e.g. https://id.biodiversity.org.au/name/apni/70914

Figure 8. Name object HTML output

Example Name object in JSON

3.3.5. NslSimpleName

3.3.6. Reference

A Reference object represents a place that a name might be published. References are categorized by their reference type. The reference types currently defined are:

1. Book

2. Chapter

3. Database

4. Herbarium annotation

5. Index

6. Journal

7. Series

8. Personal Communication

9. Database Record

10. Paper

11. Section

12. Unknown

e.g. https://id.biodiversity.org.au/reference/apni/22408

Figure 9. Name object HTML output

Example Reference object in JSON

3.3.7. Node

To be completed.

3.3.8. Tree

To be completed.

3.3.9. Branch

To be completed.

3.3.10. Event

To be completed.

3.4. Name API V1.0

The name API lets you query and manipulate names. In general to change a name you need to be authorized to do so.

The general format of a name API call is

where the things in round brackets are optional.

This is a REST API, and uses HTTP methods to determine the action. If you use the wrong HTTP method you will get an error

The services use content negotiation to determine the output type, so a content type of text/JSON gives you JSON response. The services will give an HTML response in a browser, which doesn’t include all the data available in JSON or XML.

In this document we will use JSON.

The output of services generally include standard JSON object representations of Name, Instance, Reference, [Instance Note], Author

If the name record ID doesn’t exist for any operation you will get a 404 status result with the following body (in JSON)

An action that completes will in general return a 200 status, though the action may not have 'worked'. In general an errors field with a list of error strings will be returned with a negative result field it the action doesn’t work.

If you can’t do an action (e.g. can’t delete an instance because of references to it) you will generally get a 403 with a payload containing the error message.

If you try to do an API call that requires Autorization without supplying a valid API Key, you will get an authorization error response.

3.4.1. branch

GET branch gets the APC branch for this name. This gives you a list of Names in Classification order. e.g.

Examples

• using curl

• browser

  • https://id.biodiversity.org.au/name/apni/61294/api/branch.json

Returns

• a list of Name objects from the top of the classification tree down to the name requested.

Example response

3.4.2. delete

GET delete tells you if a name can be deleted. If not it gives a list of error messages explaining why not.

DELETE delete deletes the name if it can be deleted. If not it gives a list of error messages explaining why not.

Returns

• Brief Name object

• action: 'delete'

• ok: true/false - false means you can’t delete this name

• errors: List - if ok is false this contains a list of error strings explaining the problem

if you are trying to delete and it fails (i.e. you didn’t check if you could delete it) you will get a 403 return code, with a payload containing error messages.

Example 1

Check if you can delete

response

Example 2

Non working response

Working response

3.4.3. family

GET family returns the family of the name according to the APNI or 'Name classification'. The Name classification may be different to other classifications such as APC.

Returns

• Brief name object of the name you are querying

• action: 'family'

• famlyName: the full Name object of the Family this name belongs to

Example

Example response

3.4.4. apc

GET apc tells you if this name is in the APC classification tree.

A name being in the classification tree is not the same as the name being part of the Australian Plant Census. Names in the APC tree have one of the following types:

• ApcConcept. The name is part of APC.

• ApcExcluded. An excluded name. For convenience, a boolean attribute 'excluded' is also included in the response.

• DeclaredBt. Names that, in the previous system, were declared as being "Broader Terms" of names in APC, but which were not themselves in APC.

A typical place where 'DeclaredBt' nodes appear in the tree is when several species under a genus are excluded, but where the genus itself has not been dealt with explicitly. Another place where they can appear is where a higher taxonomy is not completed for a group of names.

That is, you cannot treat 'DeclaredBt' as implying that the name is (or should be) an excluded name, or that it is (or should be) part of APC. Even in the case where a number of species in a genus have been excluded, but where the genus is a 'DeclaredBt', it may or may not be the case that the genus has another species that does appear in Australia.

Work on the Australian Plant Census is ongoing. As users of the data, all that we know about DeclaredBt names is that the name was used as a higher grouping in the previous APC system with nothing more being said about it by the APC team. We imported this data into the NSL as it was.

Returns

• The Brief name of the name in the query

• inAPC: true/false

Example

Example response

3.4.5. apni

GET apni Tells you if this name is in the APNI classification.

Returns

• The Brief name of the name in the query

• inAPNI: true/false

Example

curl -L -H "Accept: application/json" -X GET https://id.biodiversity.org.au/name/apni/54427/api/apni

Example response

3.4.6. name-strings

GET name-strings constructs the name strings for this Name using the rules in the 'ConstructedNameService' and returns them as a JSON resource. This will not change the Name object.

PUT name-strings constructs the name strings for this Name using the rules in the 'ConstructedNameService', updates the Name object with these strings, and returns them as a JSON resource.

Updating the name strings of a Name may be necessary if a name string gets out of sync with the Name data for some reason, (such as an SQL update) or the name construction algorithm has been changed.

This will re-write the full and simple names on the name object and cause the name updater to run updating NSL Simple Names and contacting anyone who has registered to get notifications of changes.

Returns

• The Brief na of the name in the query

• action: 'nameStrings'

• result:

  • fullMarkedUpName: the full name including author marked up with HTML5/XML

  • simpleMarkedUpName: the name sans author marked up with HTML5/XML

  • fullName: the full name with author in plain text

  • simpleName: the name sans author in plain text

Example 1

Response

Example 2

Response

3.4.7. name-update-event-uri

PUT name-update-event-uri to have your service notified of changes to a name register a call back URI with the NSL services using registerNameUpdateEventUri.

DELETE name-update-event-uri removes your uri from our event notification list, your service will stop being notified of name updates.

Parameters

uri: the URI you wish to put or remove

This will register your URI with the name service. when a Name change occurs this URI will be called with the type of update and the Identifier.

The type will be one of:

• create

• update

• delete

For example it may call:

http://myservice.org.au/notify/update?id=https://id.biodiversity.org.au/name/apni/70914

Your service end point can then just call that URI identifier directly to get the updated name details (see Name).

Example 1 add a URI

Response

Example 2 delete a URI

Example response

{"text":"unregistered http://localhost:8088/test"}

3.4.8. export-nsl-simple

3.4.9. apni-format / apni-format-embed

GET apni-format gets the APNI formatted output for a Name.

GET apni-format-embed gets the APNI formatted output for a Name in an embeddable format.

Example 1

https://id.biodiversity.org.au/name/apni/61294/api/apni-format

Figure 10. APNI Format HTML output

Example 1

https://id.biodiversity.org.au/name/apni/61294/api/apni-format-embed

Figure 11. APNI Format HTML embeded output

3.4.10. apc-format / apc-format-embed

GET apni-format gets the APC formatted output for a Name.

GET apni-format-embed gets the APC formatted output for a Name in an embedable format.

Parameters

embed: if set to true get the output as an embedable fragment of html.

Example 1

https://id.biodiversity.org.au/name/apni/61294/api/apc-format

Figure 12. APC Format HTML output

Example 1

https://id.biodiversity.org.au/name/apni/61294/api/apc-format-embed

Figure 13. APC Format HTML embeded output

3.4.11. simple-name

3.4.12. acceptable-name

GET acceptable-name gets a list of acceptable brief format names given the simple or full name.

An 'acceptable' name is one that is not illegitimate or illegal and has one of the following name status'

• 'legitimate'

• 'manuscript'

• 'nom. alt.'

• 'nom. cons.'

• 'nom. cons., nom. alt.'

• 'nom. cons., orth. cons.'

• 'nom. et typ. cons.'

• 'orth. cons.'

• 'typ. cons.'

Parameters

• name: the search term

Example 1

Response

3.4.13. apni-concepts

GET apni-concepts gets a JSON representation of the APNI Format information on a name. This gives a summary of the name information and the usage instances of the name in references with their relationships.

Parameters

1. relationships=false - gives you a shorter output without synonomy (see example 2), this takes less time to return.

The output us broken into two main sections, name and references. Name includes the name, its primary instance (normally the protologue), if it’s in APC and its Family.

The references section contains an ordered list of references that contain a list of 'citations', or relationship name usage instances. References without citations are stand alone references.

The citation instance link under a Reference should be used in preference to the Reference, since it contains the usage information linking the reference to a name with a relationship, including the page, e.g.:

Example

https://biodiversity.org.au/nsl/services/name/apni/71063/api/apni-concepts.json

Result

Example 2 sans relationships

https://biodiversity.org.au/nsl/services/name/apni/71063/api/apni-concepts.json?relationships=false

Result

3.4.14. find-concept

GET find-concept finds the concept (Instance) with a reference that most matches the given term. You get back the brief name plus the instance that most matched the term given. The rank field tells you how many of the tokens in the term matched the reference citation. The brief Instance tells you the reference found.

Example

https://biodiversity.org.au/nsl/services/name/apni/166271/api/find-concept.json?term=B.S. Parris (1998)

Result

3.4.15. taxon-search

GET taxon-search finds the taxon in a classification, returning the output in the Taxon Export format.

Parameters

1. q=Some name - e.g. Isopogon asper

2. tree=APC - The classification to use for the output. Currently only APC available.

Example

• using curl curl -L -H "Accept: application/json" -X GET https://biodiversity.org.au/nsl/services/api/name/taxon-search?q=Isopogon%20asper&tree=APC

• using browser (HTML result) https://biodiversity.org.au/nsl/services/api/name/taxon-search?q=Isopogon%20asper&tree=APC

• using browser (JSON result) https://biodiversity.org.au/nsl/services/api/name/taxon-search.json?q=Isopogon%20asper&tree=APC

Result

3.5. Instance API V1.0

3.5.1. delete

GET delete tells you if a Instance can be deleted. If not it gives a list of error messages explaining why not.

DELETE delete deletes the Instance if it can be deleted. If not it gives a list of error messages explaining why not.

Returns

• Brief Instance object

• action: 'delete'

• ok: true/false - false means you can’t delete this instance

• errors: List - if ok is false this contains a list of error strings explaining the problem

if you are trying to delete and it fails (i.e. you didn’t check if you could delete it) you will get a 403 return code, with a payload containing error messages.

Example: Check if you can delete

response

Failing example trying to delete

Non working response

Working example trying to delete

Working response

3.6. Reference API V1.0

3.6.1. citation-strings

GET citation-strings constructs the citation strings for this Reference using the rules in the 'ReferenceService' and returns them as a JSON resource. This will not change the Reference object.

PUT citation-strings constructs the citation strings for this Reference using the rules in the 'ReferenceService', updates the Reference object with these strings, and returns them as a JSON resource.

Updating the citation strings of a Reference may be necessary if a citation string gets out of sync with the Reference data for some reason, (such as an SQL update) or the citation construction algorithm has been changed.

This will re-write the HTML and plain citation on the Reference object.

Returns

• The Brief Reference of the reference in the query

• action: 'citation-strings'

• result:

  • citationHtml: the full citation marked up with HTML5/XML

  • citation: the citation in plain text

Example 1

Response

Example 2

Response

3.6.2. delete

GET delete tells you if a reference can be deleted. If not it gives a list of error messages explaining why not.

DELETE delete deletes the reference if it can be deleted. If not it gives a list of error messages explaining why not.

Returns

• Brief Reference object

• action: 'delete'

• ok: true/false - false means you can’t delete this name

• errors: List - if ok is false this contains a list of error strings explaining the problem

if you are trying to delete and it fails (i.e. you didn’t check if you could delete it) you will get a 403 return code, with a payload containing error messages.

Parameters

• reason - the reason this reference is being deleted.

Example 1

Check if you can delete

response

Example 2

Non working response

Working response

3.6.3. move

DELETE move move all associated resources for a reference to another reference. This is typically used in de-duplicating references that have been entered multiple times. This action will:

• redirect the URI’s associated with the source reference to the target reference,

• move all instances, comments, external references, notes, to the target reference, then

• delete the source reference.

Parameters

• target - the target reference id on the service, ie. the database ID (this is not intended for use externally)

• user - (optional) The user to blame, defaults to the administrator.

You use the resource URI as the source reference and pass the target reference ID as a parameter.

example

response

A brief target Reference object is returned along with the result "ok" to indicate success. If there are errors they will be in an errors field as a list.

3.6.4. deduplicate-marked

DELETE deduplicate-marked finds all references with duplicateOf set to another reference and calls the move action on it.

Parameters

• user - (optional) The user to blame, defaults to the administrator.

example

response

a list of de-duplicated reference DB IDs with an indication of success.

3.7. Author API V1.0

3.7.1. deduplicate

DELETE deduplicate Deduplicate author. Takes a duplicate author and replaces it with a target author. All References and Names that currently use the duplicate author will have the author replaced with the target author. The mapper is updated so that URL IDs are updated to refer to the target author. The duplicate author is then deleted from the database.

Parameters

• user - (optional) The user to blame, defaults to the administrator.

example

response

The results of deduplicating the author.

3.8. Suggestions API V1.0

The NSL infrastructure provides a number of simmple suggestions services as described in http://nerderg.com/Simple+Suggestions+plugin

The simple suggestions service is open and provides a way to do a simple type ahead or suggestion for search results to do with names, references and authors in the NSL.

The suggestion service works on a set of subjects where you provide a search term, and the service give