API Design

Following, I will define all the calls that you can make to this service:

Input formats:

• GET /input/supported -> Lists the supported input formats. This returns a list of input formats supported by at least one of the tools. It is a convenience call. The list can include MIME types or other if a specific formats used. (Output can be easy configurable)
• GET /input/{id} Provides additional information on an input format. If applicable and not a simple MIME type, provides additional description on the input format required. (Output can be easy configurable)

Interlinking tools:

• GET /tool/list -> Lists the tools currently available on the service. This returns a list of the tools that are currently installed and available for querying. Note that the same external software package can appear as several tools in the service, if it is configured differently
• GET /tool/{id} -> Gets the information on the tool. This returns a list of the tools that are currently installed and available for querying. Note that the same external software package can appear as several tools in the service, if it is configured differently. The common information for all the tools is the following:

{
      “id” : “<tool id>”,
      “inputs-supported” : [ {“id”=””},  {“id”=””} …  ]  
}

• GET /tool/{id}/response-fields -> Provides tools specific fields. This returns the fields of a tool that are not in common with the rest. It can be specific because the field is not provided by all the other tools or because the format given is different. e.g. The confidence could be given as a percentage from 0 to 100 or using tags like “Equivalent”, “Approximate” … The information will be given like this:

{
      “id” : “<tool id>”,
      “specific-fields” : [ {“id”=””},  {“id”=””} …  ]  
}

• GET /tool/{id}/response-fields/{id} -> Provides information about a specific field from a tool. This returns the information of a specific field of a tool. It can be specific because the field is not provided by all the other tools or because the format given is different. The information provided will be the specific field and its format The information will be given like this:

{
      “id” : “<tool id>”, 
      “id” : “<specific-field id>”,
      “format-specific-field” : [ {“format”},  {“format”} …  ]  
}

Simple text interlinking:

• POST /fromtext/links/?tool={tool-id}&text=value -> Invokes an interlinking service passing text as input. This returns a list with the words from the text that has links with external datasets. For each item is also shown ‘relevance’ in the text (a double between 0.0 and 1.0 as percentage), ‘count’ (number of occurrences) and ‘confidence’ (to measure the quality of the alignment, measures as relevance)

{
      “uri” : “<string>”,
      “phrase” : “<string>”,
      “relevance” : “<double>”,
      “count” : “<integer>”,
      “confidence” : “<double>”
}

• POST /fromtext/top_links/?tool={tool-id}&text=value&limit=value -> Invokes an interlinking service passing text as input. This returns a list with the words from the text that has links with external datasets. The number of items in the list is limited by the argument “limit” and is ordered from the highest to the lowest. For each item is also shown ‘relevance’ in the text (a double between 0.0 and 1.0 as percentage), ‘count’ (number of occurrences) and ‘confidence’ (to measure the quality of the alignment, measures as relevance)

{
      “uri” : “<uri string>”,
      “phrase” : “<string>”,
      “relevance” : “<double>”,
      “count” : “<integer>”,
      “confidence” : “<double>”
}

• POST /text/links/?tool={tool-id}&text=value -> Invokes an interlinking service passing an uri that contains a text as input. This returns a list with the words from a text stored in an uri that has links with external datasets. For each item is also shown ‘relevance’ in the text (a double between 0.0 and 1.0 as percentage), ‘count’ (number of occurrences) and ‘confidence’ (to measure the quality of the alignment, measures as relevance)

{
      “uri” : “<string>”,
      “phrase” : “<string>”,
      “relevance” : “<double>”,
      “count” : “<integer>”,
      “confidence” : “<double>”
}

• POST /text/top_links/?tool={tool-id}&text=value&limit=value -> Invokes an interlinking service passing an uri that contains a text as input. This returns a list with the words from a text stored in an uri that has links with external datasets. The number of items in the list is limited by the argument “limit” and is ordered from the highest to the lowest. For each item is also shown ‘relevance’ in the text (a double between 0.0 and 1.0 as percentage), ‘count’ (number of occurrences) and ‘confidence’ (to measure the quality of the alignment, measures as relevance)

{
      “uri” : “<uri string>”,
      “phrase” : “<string>”,
      “relevance” : “<double>”,
      “count” : “<integer>”,
      “confidence” : “<double>”
}