NSL API Documentation
v1.0, June 2015 (Main documentation for the NSL API version 1.0)
- 1 1. Introduction
- 2 2. Using the NSL
- 2.1 2.1. Searching the NSL
- 2.2 What is a tree?
- 2.2.1 2.1.1. Name Search
- 3 3. Application Interfaces (APIs)
- 3.1 3.1. Changes
- 3.2 3.2. Linked Data
- 3.3 3.3. Basic Resource Objects
- 3.3.1 3.3.1. Author
- 3.3.2 3.3.2. Instance
- 3.3.3 3.3.3. InstanceNote
- 3.3.4 3.3.4. Name
- 3.3.5 3.3.5. NslSimpleName
- 3.3.6 3.3.6. Reference
- 3.3.7 3.3.7. Node
- 3.3.8 3.3.8. Tree
- 3.3.9 3.3.9. Branch
- 3.3.10 3.3.10. Event
- 3.4 3.4. Name API V1.0
- 3.4.1 3.4.1. branch
- 3.4.2 3.4.2. delete
- 3.4.3 3.4.3. family
- 3.4.4 3.4.4. apc
- 3.4.5 3.4.5. apni
- 3.4.6 3.4.6. name-strings
- 3.4.7 3.4.7. name-update-event-uri
- 3.4.8 3.4.8. export-nsl-simple
- 3.4.9 3.4.9. apni-format / apni-format-embed
- 3.4.10 3.4.10. apc-format / apc-format-embed
- 3.4.11 3.4.11. simple-name
- 3.4.12 3.4.12. acceptable-name
- 3.4.13 3.4.13. apni-concepts
- 3.4.14 3.4.14. find-concept
- 3.4.15 3.4.15. taxon-search
- 3.5 3.5. Instance API V1.0
- 3.5.1 3.5.1. delete
- 3.6 3.6. Reference API V1.0
- 3.6.1 3.6.1. citation-strings
- 3.6.2 3.6.2. delete
- 3.6.3 3.6.3. move
- 3.6.4 3.6.4. deduplicate-marked
- 3.7 3.7. Author API V1.0
- 3.7.1 3.7.1. deduplicate
- 3.8 3.8. Suggestions API V1.0
- 3.9 3.9. Tree Structure V1.0
- 3.9.1 3.9.1. Overall Structure
- 3.9.1.1 Nodes and Links
- 3.9.1.2 Arrangements
- 3.9.1.3 Lifecycle
- 3.9.1.4 History
- 3.9.2 3.9.2. Arrangement, Node, and Link internal types
- 3.9.2.1 Arrangement types
- 3.9.2.2 Node types
- 3.9.2.3 Link types
- 3.9.3 3.9.3. Node content and Node and Link RDF types
- 3.9.4 3.9.4. Classification trees
- 3.9.1 3.9.1. Overall Structure
- 3.10 3.10. Tree API for JSON V1.0
- 3.10.1 3.10.1. tree view services
- 3.10.1.1 listNamespaces
- 3.10.1.2 listClassifications
- 3.10.1.2.1 Example 1
- 3.10.1.3 listWorkspaces
- 3.10.1.3.1 Example 1
- 3.10.1.4 permissions
- 3.10.2 3.10.2. JSON views of nodes, arrangements, and events
- 3.10.3 3.10.3. Tree Edit Services
- 3.10.3.1 createWorkspace
- 3.10.3.2 deleteWorkspace
- 3.10.3.3 updateWorkspace
- 3.10.1 3.10.1. tree view services
- 3.11 3.11. SPARQL and the semantic web
- 3.11.1 3.11.1. Linked data and semantic web integration
- 3.11.1.1 Static vocabulary
- 3.11.1.2 Data items
- 3.11.2 3.11.2. Overall content
- 3.11.2.1 Vocabulary and metadata
- 3.11.2.2 Outdated APNI, AFD, and CoL data
- 3.11.2.3 NSL data
- 3.11.3 3.11.3. The NSL data model and its RDF representation
- 3.11.1 3.11.1. Linked data and semantic web integration
- 3.12 3.12. Export
- 3.12.1 3.12.1. Exports
- 3.12.1.1 Names export
- 3.12.1.1.1 example APNI name output
- 3.12.1.2 Taxon export
- 3.12.1.2.1 example APC taxon output
- 3.12.1.1 Names export
- 3.12.1 3.12.1. Exports
- 3.13 Notes
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
APNI and APC
Mosses (AusMoss)
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:
Fungi
Algae
Mosses
Lichen
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".
What is a tree?
We may speak of "trees" when referring to classifications in the NSL system, which shouldn’t be confused with actual woody vascular plants. A tree in this sense is the structure of set of names: where one name is in relation to other names. For example, the plant family name is "above" the names of its constituent genera, a genus name ranks "below" the family in the tree. A family may contain many genera and each genus many species and so on.
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.
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.
This search just looks at the full name text, it is not trying to comprehend the name or its placement in a classification.
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.
You don’t have to click on or use the suggestions, just press enter or click the search button with your query.
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.
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:
https://id.biodiversity.org.au/[objectType]/[namespace]/[random unique number]
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)
{
"class": "au.org.biodiversity.nsl.Author",
"_links": {
"permalinks": [
{
"link": "https://id.biodiversity.org.au/1441",
"resources": 1
},
{
"link": "https://id.biodiversity.org.au/author/apni/1441",
"resources": 1
}
]
},
"audit": {
"created": {
"by": "LADAMS",
"at": "2002-02-13T13:00:00Z"
},
"updated": {
"by": "LADAMS",
"at": "2002-02-13T13:00:00Z"
}
},
"namespace": "APNI",
"abbrev": "R.Br.",
"name": "Brown, R.",
"fullName": null,
"dateRange": null,
"notes": null,
"ipniId": null,
"duplicateOf": null,
"references": [],
"names": [
{
"class": "au.org.biodiversity.nsl.Name",
"_links": {
"permalink": {
"link": "https://id.biodiversity.org.au/name/apni/82208",
"resources": 1
}
},
"nameElement": "crassifolius"
},
{
"class": "au.org.biodiversity.nsl.Name",
"_links": {
"permalink": {
"link": "https://id.biodiversity.org.au/name/apni/128739",
"resources": 1
}
},
"nameElement": "reflacta"
},
... //(1000s of names)
],
baseNames: [...],
exNames: [...],
exBaseNames: [...]
}
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:
replaced synonym
basionym
pro parte replaced synonym
nomenclatural synonym
doubtful nomenclatural synonym
pro parte nomenclatural synonym
pro parte misapplied
doubtful misapplied
doubtful pro parte misapplied
taxonomic synonym
pro parte taxonomic synonym
doubtful taxonomic synonym
doubtful pro parte taxonomic synonym
synonym
pro parte synonym
doubtful synonym
doubtful pro parte synonym
isonym
autonym
trade name
comb. et stat. nov.
comb. nov.
comb. et nom. nov.
misapplied
nom. et stat. nov.
nom. nov.
tax. nov.
excluded name
doubtful invalid publication
primary reference
homonym
invalid publication
[n/a]
[unknown]
sens. lat.
common name
vernacular name
[default]
secondary reference
implicit autonym
orthographic variant
As you can see the instance type describes the relationship of the reference to the name.
Basic Instance object structure
{
"instance": {
"class": "au.org.biodiversity.nsl.Instance",
"_links": {...}, //links to this object and related resources
"audit": {...}, //change information
"namespace": "APNI", //The shard or dataset this instance belongs to
"verbatimNameString": "Doodia R.Br.", //The name string as written in the reference
"page": "151", //The page(s) of the reference this useage was found
"pageQualifier": null, //
"nomenclaturalStatus": null,
"bhlUrl": null, //link to Biodiversity Heritage Librabry http://www.biodiversitylibrary.org/
"instanceType": {},
"name": {},
"reference": {},
"parent": {}, //Parent instance todo: explain
"cites": {}, //An Instance that this instance cites
"citedBy": {}, //An Instance that this instance is cited by
"externalRefs": [],
"instancesForCitedBy": [],
"instancesForCites": [...],
"instancesForParent": [],
"instanceNotes": [...]
}
}
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:
Neotype
Ex.distribution
APC Comment
EPBC Impact
Status
Under
Distribution
URL
Lectotype
Context
Vernacular
Text
Comment
Synonym
Type
APC Dist.
Etymology
EPBC Advice
APNI
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.
| This shouldn’t be confused with the Taxon, which is more correctly described by the Protologue Instance of a Name. |
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:
Book
Chapter
Database
Herbarium annotation
Index
Journal
Series
Personal Communication
Database Record
Paper
Section
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
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.
| this is currently only available as HTML |
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
| this has been removed. |
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
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
q=Some name - e.g. Isopogon asper
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.
| You need to be an administrator, or administrator service to call this with the 'DELETE' method. Use your apiKey to authenticate. |
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