Suggested Concepts Services

Abstract

Suggested concept services provide methods to manage concepts that were introduced from outside PoolParty as potential future concepts.

A typical use case for suggesting new concepts is the extension of the thesaurus for example by terms that are extracted during Concept Extraction Service.

Please find more details how PoolParty handles the Suggested Concepts Workflow.

Web Service Method: Suggest Concept

Abstract

Web Service Method: Suggest Concept

Description
This service provides a way to suggest a new concept.

Note

This method returns the generated URI of the created concept that appears under "Suggested Concepts" in the targeted project in tab "Workflow Dashboard". For details refer to: Suggested Concepts Workflow

If you want to create a narrower concept directly, without using the Suggested Concepts List, you may consider to use the Web Service Method: Create New Concept.

URL: /PoolParty/api/thesaurus/{project}/suggestConcept

Note

You have to provide a prefLabel in the default language. You can only suggest labels in languages that are defined as project language.

Request

Supported Methods
POST

Content-Type: application/json

Path Variables

Variable	Comment
`{project}`	The UUID or the URI supplement (textual identifier) of the project to be used.

JSON Request Object

Request object to suggest a new concept.

Attribute	Type	Required	Comment
`prefLabels`	Array of LanguageLiterals	true	Object consisting of label (String) and language (String)
`checkForDuplicates`	boolean	false	If another concept with the same preferred label already exists, an error will be thrown. (Default: true)
`broaderConcept`	Array of URIs	false	Parent concept of the suggested concept.
`topConceptOf`	Array of URIs	false	Parent concept scheme of the suggested concept. This means, the suggested concept will become a top concept.
`relatedConcept`	Array of URIs	false	Related concepts of the suggested concept.
`definition`	Array of LanguageLiterals	false	Object consisting of `label` (String) and `language` (String)
`note`	String	false	Notes describing the suggested concept.
`score`	float	false	Custom score for the new concept between `0` and `1`.
suffix	String	false	Optional parameter that lets the client define the URI suffix in case the project has a Manual ID generation pattern.

Response

HTTP status code 200 if OK + the URL of the suggested concept.

ExamplesUse Case I: Suggest Concept with a Concept as Parent - broaderConcept Used

POST <server-url>/PoolParty/api/thesaurus/{project}/suggestConcept
Content-Type: application/json

{
  "prefLabels": [
    {
      "label":"Headache",
      "language":"en"
    }
  ],
  "broaderConcept": [
    {
      "uri":"http://id.nlm.nih.gov/mesh/D006257"
    }
  ],
  "checkForDuplicates" : true,
  "note" : "Suggested by florian",
  "definition" : [
    {
      "label":"Pain in the head.",
      "language":"en"
    }
    ]
}

Use Case II: Suggest Concept with a Concept Scheme as Parent - topConceptOf Used

POST <server-url>/PoolParty/api/thesaurus/{project}/suggestConcept
Content-Type: application/json

{
  "prefLabels": [
    {
      "label":"Asia",
      "language":"en"
    }
  ],
  "topConceptOf": [
    {
      "uri":"http://vocabulary.poolparty.biz/geo/0"
    }
  ],
  "note" : "Asia as new top concept of our geo project.",
  "definition" : [
    {
      "label":"Continent",
      "language":"en"
    }
    ]
}

Usage of a REST Client

The following screenshot shows the usage of the suggest concept service with the Advanced REST Client:

The following screenshot shows the usage of the import service using Postman:

Web Service Method: Suggest Multiple Concepts

Abstract

Web Service Method: Suggest Multiple Concepts

Description
This service allows to suggest multiple concepts in one request.

It returns the generated URIs of the created concepts that are accessible in the "Workflow Dashboard". Please see: Suggested Concepts Workflow

URL: /PoolParty/api/thesaurus/{project}/suggestConcepts

Note

You have to provide a prefLabel in the default language. You can only suggest labels in languages that are defined as project language.

Note

Using this service might be useful in case you want to prevent to use the request Web Service Method: Suggest Concept multiple times.

If you want to create a narrower concept directly, without using the Suggested Concepts List, you may consider to use Web Service Method: Create New Concept.

Request

Supported Methods
POST

Content-Type: application/json

Path Variables

Variable	Comment
`{project}`	The UUID or the URI supplement (textual identifier) of the project to be used.

JSON Request Object

Request object to suggest a new concept.

Attribute	Attribute	Type	Required	Comment
`conceptSuggestRequests`			true	Envelope for an array of suggested concepts
	`prefLabels`	Array of LanguageLiterals	true	Object consisting of label (String) and language (String)
	`checkForDuplicates`	boolean	false	If another concept with the same preferred label already exists, an error will be thrown. (Default: true)
	`broaderConcept`	Array of URIs	false	Parent concept of the suggested concept.
	`topConceptOf`	Array of URIs	false	Parent concept scheme of the suggested concept. This means, the suggested concept will become a top concept.
	`relatedConcept`	Array of URIs	false	Related concepts of the suggested concept.
	`definition`	Array of LanguageLiterals	false	Object consisting of `label` (String) and `language` (String)
	`note`	String	false	Notes describing the suggested concept.
	`score`	float	false	Custom score for the new concept between `0` and `1`.
	`suffix`	String	false	Optional parameter that lets the client define the URI suffix in case the project has a Manual ID generation pattern.

Response

HTTP status code 200 if OK + the URL of the suggested concept.

ExamplesUse Case: Suggest Two Concepts at Once

POST https://preview.poolparty.biz/PoolParty/api/thesaurus/1DDFD8F0-F0B1-0001-254A-1A3047C67540/suggestConcepts
Content-Type: application/json

{
        "conceptSuggestRequests": [
                {
                        "prefLabels": [
                                {
                                        "label":"Hillary Clinton",
                                        "language":"en"
                                        
                                }
                        ],
                        "definition" : [
                        {
                                "label":"Democratic Party presidential candidate",
                                "language":"en"
                        }
                ]
                }, 
                {
                        "prefLabels": [
                                {
                                        "label":"Donald Trump",
                                        "language":"en"
                                }
                        ],
                        "definition" : [
                        {
                                "label":"Republican Party presidential candidate",
                                "language":"en"
                        }
                ]
                }
        ]
}

Example Response

 [
  {
    "uri": "https://preview.poolparty.biz/TestCooccurrences/167"
  },
  {
    "uri": "https://preview.poolparty.biz/TestCooccurrences/168"
  }
]

Usage of a REST Client

The following screenshot shows how two concepts are suggested, using Postman:

Web Service Method: Request Suggested Concept

Abstract

Web Service Method: Request Suggested Concept

Description
Provides details about a selected suggested concept.

Note

This service is equivalent to details you can find in the Suggested Concepts list in the Workflow Dashboardtab in the PoolParty frontend. For details refer to: Suggested Concepts Workflow

URL: /PoolParty/api/thesaurus/{project}/suggestedConcept

Request

Supported Methods
GET

Path Variables

Variable	Comment
`{project}`	The UUID or the URI supplement (textual identifier) of the project to be used.

HTTP Parameters

Parameter	Comment	Type	Required
concept	URI of the suggested concept	String	true

Response

HTTP status code 200 if OK + a JSON formatted response.

Attribute	Type	Comment
`uri`	String	URI of the concept
`prefLabels`	Object, containing label and language	Array of preferred labels of suggested concept. A suggested concept may carry labels in different languages.
`definitions`	Array of Strings	Suggested concepts may carry alternative labels.
`broaderResources`	Array of Strings	Suggested concepts may carry broader concepts.
`relatedResources`	Array of Strings	Suggested concepts may carry related concepts.
`note`	String	Suggested concepts may carry a note.
`score`	float	Custom score for the new concept between 0 and 1.
`date`	Date	Last modification date

Example

cURL Request

curl -u user:password -X GET "http://vocabulary.semantic-web.at/PoolParty/api/thesaurus/1DCE0ED2-D7E8-0001-86A1-18652DF0D7A0/suggestedConcept?concept=http://vocabulary.semantic-web.at/cocktails/4c6a85a7-de2a-42a9-9664-3279e53bac48"

Example Response

{
  "uri" : {
    "uri" : "http://vocabulary.semantic-web.at/cocktails/4c6a85a7-de2a-42a9-9664-3279e53bac48"
  },
  "prefLabels" : [ {
    "label" : "Calvados",
    "language" : "en"
  } ],
  "definitions" : [ ],
  "broaderResources" : [ ],
  "relatedResources" : [ ],
  "score" : 0.0,
  "date" : 1452700150000,
  "note" : ""
}

Web Service Method: Request Suggested Concepts of a Project

Abstract

Web Service Method: Request Suggested Concepts of a Project

Description
Returns the list of suggested concepts for the specified project.

Note

This service is equivalent to the list of the Suggested Concepts in the Workflow Dashboard tab in PoolParty frontend. For details refer to:Suggested Concepts Workflow

URL: /PoolParty/api/thesaurus/{project}/suggestedConcepts

Request

Supported Methods
GET

Path Variables

Variable	Comment
`{project}`	The UUID or the URI supplement (textual identifier) of the project to be used.

HTTP Parameters

Parameter	Comment	Type	Required
offset	Start index from where the suggested concepts results should be returned.	integer	false
noOfConcepts	The number of retrieved suggested concepts.	integer	false

Response

HTTP status code 200 if OK + a JSON formatted response.

Attribute	Type	Comment
`uri`	String	URI of the concept
`prefLabels`	Object, containing label and language	Array of preferred labels of suggested concept. A suggested concept may carry labels in different languages.
`definitions`	Array of Strings	Suggested concepts may carry alternative labels.
`broaderResources`	Array of Strings	Suggested concepts may carry broader concepts.
`relatedResources`	Array of Strings	Suggested concepts may carry related concepts.
`note`	String	Suggested concepts may carry a note.
`score`	float	Custom score for the new concept between 0 and 1.
`date`	Date	Last modification date

Example

cURL request

curl -u user:password -X GET "http://vocabulary.semantic-web.at/PoolParty/api/thesaurus/1DCE0ED2-D7E8-0001-86A1-18652DF0D7A0/suggestedConcepts"

Example Response

[ {
  "uri" : {
    "uri" : "http://vocabulary.semantic-web.at/cocktails/4c6a85a7-de2a-42a9-9664-3279e53bac48"
  },
  "prefLabels" : [ {
    "label" : "Calvados",
    "language" : "en"
  } ],
  "definitions" : [ ],
  "broaderResources" : [ ],
  "relatedResources" : [ ],
  "score" : 0.0,
  "date" : 1452700150000,
  "note" : ""
}, {
  "uri" : {
    "uri" : "http://vocabulary.semantic-web.at/doku/test-concept"
  },
  "prefLabels" : [ {
    "label" : "test concept",
    "language" : "en"
  }, {
    "label" : "Testkonzept",
    "language" : "de"
  } ],
  "definitions" : [ ],
  "broaderResources" : [ {
    "uri" : "http://vocabulary.semantic-web.at/doku/University-of-Vienna"
  } ],
  "relatedResources" : [ ],
  "score" : 0.0,
  "date" : 1447947012000,
  "note" : ""
} ]

Usage of a REST client

The following screenshot shows the request for the first five suggested concepts of a project using Postman:

Web Service Method: Delete Suggested Concept

Abstract

Web Service Method: Delete Suggested Concept

Description
Deletes a suggested concept from the free concepts list in PoolParty.

Note

This service is equivalent to the list of the Suggested Concepts in the Workflow Dashboard tab in PoolParty frontend. For details refer to:Suggested Concepts Workflow

URL: /PoolParty/api/thesaurus/{project}/suggestedConcept?uri={uri}

Request

Supported Methods
DELETE

Content-Type: application/json

Path Variables

Parameter	Type	Required	Description
{project}	String	true	The UUID or the URI supplement (textual identifier) of the project to be used.
`uri`	String	true	The uri value of the concept you want to delete.

Response

HTTP status code 204 if OK.

Usage of a REST Client

The following screenshot shows the usage of the delete service using Postman:

Web Service Method: Delete Suggested Concepts

Abstract

Web Service Method: Delete Suggested Concepts

Description
Deletes multiple suggested concepts from the free concepts list in PoolParty.

Note

This service is equivalent to the list of the Suggested Concepts in the Workflow Dashboard tab in PoolParty frontend. For details refer to:Suggested Concepts Workflow

URL: /PoolParty/api/thesaurus/{project}/suggestedConcepts

Request

Supported Methods
DELETE

Content-Type: application/json

Path Variables

Parameter	Type	Required	Description
{project}	String	true	The UUID or the URI supplement (textual identifier) of the project to be used.

JSON Request Object

Request object to delete a suggested concept.

Attribute

Type

Required

Comment

uri

Array of Strings

true

URIs of the suggested concepts.

If there is one wrong concept URI, an error will be thrown.

Response

HTTP status code 204 if OK.

Usage of a REST Client

The following screenshot shows the usage of the import service using Postman:

Web Service Method: Update a Suggested Concept

Abstract

Web Service Method: Update a Suggested Concept

Description
Updates an existing suggested concept.

Note

This service is equivalent to the list of the Suggested Concepts in the Workflow Dashboard tab in PoolParty frontend. For details refer to:Suggested Concepts Workflow

URL: /PoolParty/api/thesaurus/{project}/suggestedConcept?uri={uri}

Request

Supported Methods
PATCH

Content-Type: application/json

Path Variables

Parameter	Type	Required	Description
{project}	String	true	The UUID or the URI supplement (textual identifier) of the project to be used.
`uri`	String	true	URI of the concept to be updated. If no concept with given URI exists, an error will be thrown.

JSON Request Object

Request object to suggest a new concept.

Attribute	Type	Required	Comment
prefLabels	Array of LanguageLiterals	false	Object consisting of label (String) and language (String).
checkForDuplicates	boolean	false	If another concept with the same preferred label already exists, an error will be thrown. (Default: true).
broaderConcept	Array of URIs	false	Parent concept of the suggested concept.
topConceptOf	Array of URIs	false	Parent concept scheme of the suggested concept. This means, the suggested concept will become a top concept.
relatedConcept	Array of URIs	false	Related concepts of the suggested concept.
definition	Array of LanguageLiterals	false	Object consisting oflabel(String) andlanguage(String)
note	String	false	Notes describing the suggested concept.
score	float	false	Custom score for the new concept between0and1.
suffix	String	false	Optional parameter that lets the client define the URI suffix in case the project has aManual ID generation pattern.

Response

HTTP status code 204 if OK.

ExamplesUse Case I: Suggest Concept with a Concept as Parent - broaderConcept Used

PATCH
<server-url>/PoolParty/api/thesaurus/{project}/suggestedConcept
Content-Type: application/json
 
{
  "prefLabels": [
    {
      "label":"Headache",
      "language":"en"
    }
  ],
  "broaderConcept": [
    {
      "uri":"http://id.nlm.nih.gov/mesh/D006257"
    }
  ],
  "checkForDuplicates" : true,
  "note" : "Suggested by florian",
  "definition" : [
    {
      "label":"Pain in the head.",
      "language":"en"
    }
    ]
}

Use Case II: Suggest Concept with a Concept Scheme as Parent - topConceptOf Used

PATCH <server-url>/PoolParty/api/thesaurus/{project}/suggestedConcept
Content-Type: application/json
 
{
  "prefLabels": [
    {
      "label":"Asia",
      "language":"en"
    }
  ],
  "topConceptOf": [
    {
      "uri":"http://vocabulary.poolparty.biz/geo/0"
    }
  ],
  "note" : "Asia as new top concept of our geo project.",
  "definition" : [
    {
      "label":"Continent",
      "language":"en"
    }
    ]
}

Usage of a REST Client

The following screenshot shows the usage of the update service using Postman:

In this section: