Getting started for API Users
This article shall give the API-user an idea how to use the FREME API.
How to create an API request
The following URL represents a simple API call which returns all publicly available datasets of FREME-NER: https://api.freme-project.eu/current/e-entity/freme-ner/datasets.
This call uses the default HTTP method GET. With the Http method POST you can send data to the server which then returns the processed data. A POST request cannot simply be executed by the browser as it is possible with GET. There are several tools that can be used, e.g. Postman, Poster or curl. The endpoints that FREME provides are specified in the complete API documentation where you can also try them out. When you make an API call there the corresponding curl - command will be generated.
curl -X POST --header 'Content-Type: text/plain' --header 'Accept: text/turtle' 'https://api.freme-project.eu/current/e-entity/dbpedia-spotlight/documents?input=Welcome%20to%20Berlin%2C%20the%20capital%20of%20Germany.&numLinks=1&language=en&confidence=0.3'
This example call to e-entity/dbpedia-spotlight/documents which spots entities in the data you send via the input parameter. The call specifies two headers, Content-Type and Accept. The Content-Type header exists for both the request and the response, it refers to the dataformat of the data that was send to or back from the service. The Accept-header specifies which dataformat you want to accept for the response. These headers are not mandatory, but it is highly recommended to set them. The tools, e.g. Postman, or browsers may set them implicitly if they are not specified which can result in unexpected behaviour.
Input Types
| Format | Content-Type header | remarks | |
|---|---|---|---|
| NIF | turtle | text/turtle | default |
| rdf-xml | text/rdf-xml | ||
| json | application/ld+json | ||
| N-Triples | application/n-triples | ||
| N3 | text/n3 | ||
| Plaintext | plain | text/plain | standard |
| e-internationalization | xliff 1.2 | application/x-xliff+xml | Makes it possible to upload files with different format than NIF. |
| ODT | application/x-openoffice | ||
| xml | text/xml | ||
| html | text/html | ||
| XSLT Converter | xml | text/xml | Use XSLT-converter to transform xml and html files with xslt stylesheets. |
| html | text/html |
Output Types
| Format | Accept header | remarks | |
|---|---|---|---|
| NIF | turtle | text/turtle | default |
| rdf-xml | text/rdf-xml | ||
| json | application/ld+json | ||
| N-Triples | application/n-triples | ||
| N3 | text/n3 | ||
| e-internationalization | xliff 1.2 | application/x-xliff+xml | For the e-internationalization formats the output type must be the same as the input type. |
| ODT | application/x-openoffice | ||
| xml | text/xml | ||
| html | text/html | ||
| SPARQL-converter outputs | csv | text/comma-seperated-values | default |
| json | application/json | ||
| xml | text/xml | ||
| RDF formats | Must be accepted by FREME enrichment services. | ||
| XSLT Converter | xml | text/xml | Use XSLT-converter to transform xml and html files with xslt stylesheets. |
| html | text/html |
Retrieve input from an URL
When you want to process text from an url, you can set the parameter intype to url and specify the url in the input (or its short version i) - parameter. If you do not send a Content-Type Header nor specify the informat parameter, the default Content-Type text/turtle is used. Below you can see an example call to FREME-NER where the text to be processed is retrieved from an URL.
curl -X POST 'https://api.freme-project.eu/current/e-entity/freme-ner/documents?language=en&dataset=dbpedia&mode=all&intype=url&input=http://beautifulberlin.blogspot.de/2009/07/short-history-of-berlin.html&filter=extract-entities-only&outformat=csv&informat=text/html'
Use Apache Tika to process content from files
You can also process text from a file of a format that is supported by Tika. In this case, you have to specify the following two additional parameters in your request:
- filename=THE_NAME_OF_YOUR_FILE
- informat=TIKAFile
FREME Postman collection
Postman is a handy and free tool to execute and archive your commonly used HTTP requests. We publish a collection of pre-build FREME API calls that can be executed against the FREME Demo APIs or against your own local FREME installations. These collections can also be used to generate API calls in programming languages such as Java, PHP, jQuery and others.
How to use the collection: Import this Postman collection into your local Postman to have a set of working requests which covers the most of FREME functionality out of the box. To get this collection working just define the Postman variable baseUrl and set it to api.freme-project.eu/current, for instance. Furthermore, if you intend to create or modify restricted resources like FREME templates, filters, etc. you have to define and set the variable token to the one you get when you have authenticated successfully.
Natural Language Interchange Format (NIF)
The Natural Language Processing interchange format (NIF) is the default output format of all FREME e-Services. This is an RDF based data format that can be serialized in different formats such as turtle, rdf-xml and others. When you create a pipeline then internally the pipeline should speak NIF to make sure that all pipeline steps are compatible to each other. You can either parse the output of FREME directly using a suitable RDF library our you can use the Postprocessing Filters to get a more traditional output format. You can find more information about NIF in these slides or the official NIF reference.