You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jena.apache.org by "karolina-telicent (via GitHub)" <gi...@apache.org> on 2024/06/14 10:33:57 UTC
[PR] prefixes-service documentation [jena-site]
karolina-telicent opened a new pull request, #188:
URL: https://github.com/apache/jena-site/pull/188
Documentation for https://github.com/apache/jena/pull/2538#issue-2353046667
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] prefixes-service documentation [jena-site]
Posted by "afs (via GitHub)" <gi...@apache.org>.
afs commented on code in PR #188:
URL: https://github.com/apache/jena-site/pull/188#discussion_r1681586962
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
+```
+will return http://www.localhost.org/uri1.
+
+A POST request
+```
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
+```
+will result in the update of the database:
+
+| prefix | uri |
+|---------|----------------------------------|
+| prefix1 | http://www.localhost.org/newuri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+Incorrectly formed requests
+```
+// prefix is not valid
+http://localhost:port/prefixes?prefix=.prefix1&uri=http://www.localhost.org/newuri1
+
+// incorrect parameter name
+http://localhost:port/prefixes?p=prefix1&uri=http://www.localhost.org/newuri1
+
+// illegal combination of parameter values
Review Comment:
```suggestion
// illegal combination of parameter values for DELETE
```
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
+```
+will return http://www.localhost.org/uri1.
+
+A POST request
+```
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
+```
+will result in the update of the database:
+
+| prefix | uri |
+|---------|----------------------------------|
+| prefix1 | http://www.localhost.org/newuri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+Incorrectly formed requests
+```
+// prefix is not valid
+http://localhost:port/prefixes?prefix=.prefix1&uri=http://www.localhost.org/newuri1
Review Comment:
```suggestion
http://localhost:port/dataset/prefixes?prefix=.prefix1&uri=http://www.localhost.org/newuri1
```
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
+```
+will return http://www.localhost.org/uri1.
+
+A POST request
+```
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
+```
+will result in the update of the database:
+
+| prefix | uri |
+|---------|----------------------------------|
+| prefix1 | http://www.localhost.org/newuri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+Incorrectly formed requests
+```
+// prefix is not valid
+http://localhost:port/prefixes?prefix=.prefix1&uri=http://www.localhost.org/newuri1
+
+// incorrect parameter name
+http://localhost:port/prefixes?p=prefix1&uri=http://www.localhost.org/newuri1
+
+// illegal combination of parameter values
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1&prefixtoremove=prefix2
+```
+result in HTTP exception: 400 - Bad Request.
+
+## Configuration
+
+The services is configured via a standard Fuseki config file. Example file for a Prefixes Services with a TDB2 database at `data/DB2`:
+
+```
+PREFIX example: <http://example.org/fuseki/>
+PREFIX ex: <http://example.org/fuseki/operation/>
+PREFIX fuseki: <http://jena.apache.org/fuseki#>
+PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX : <http://telicent.io/config#>
+PREFIX ja: <http://jena.hpl.hp.com/2005/11/Assembler#>
+PREFIX tdb2: <http://jena.apache.org/2016/tdb#>
+
+:service rdf:type fuseki:Service ;
+ fuseki:name "dataset" ;
+ fuseki:endpoint [ fuseki:operation fuseki:query ; ] ;
+ fuseki:endpoint [ fuseki:operation fuseki:update ; ] ;
+
+ fuseki:endpoint [ fuseki:operation ex:prefixes-r ; fuseki:name "prefixes" ] ;
+ fuseki:endpoint [ fuseki:operation ex:prefixes-rw ; fuseki:name "updatePrefixes" ] ;
Review Comment:
```suggestion
fuseki:endpoint [ fuseki:operation ex:prefixes-rw ; fuseki:name "prefixes-rw" ] ;
```
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
+```
+will return http://www.localhost.org/uri1.
+
+A POST request
+```
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
+```
+will result in the update of the database:
+
+| prefix | uri |
+|---------|----------------------------------|
+| prefix1 | http://www.localhost.org/newuri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+Incorrectly formed requests
+```
+// prefix is not valid
+http://localhost:port/prefixes?prefix=.prefix1&uri=http://www.localhost.org/newuri1
+
+// incorrect parameter name
+http://localhost:port/prefixes?p=prefix1&uri=http://www.localhost.org/newuri1
Review Comment:
```suggestion
http://localhost:port/dataset/prefixes?p=prefix1&uri=http://www.localhost.org/newuri1
```
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
+```
+will return http://www.localhost.org/uri1.
+
+A POST request
+```
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
+```
+will result in the update of the database:
+
+| prefix | uri |
+|---------|----------------------------------|
+| prefix1 | http://www.localhost.org/newuri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+Incorrectly formed requests
+```
+// prefix is not valid
+http://localhost:port/prefixes?prefix=.prefix1&uri=http://www.localhost.org/newuri1
+
+// incorrect parameter name
+http://localhost:port/prefixes?p=prefix1&uri=http://www.localhost.org/newuri1
+
+// illegal combination of parameter values
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1&prefixtoremove=prefix2
Review Comment:
```suggestion
http://localhost:port/prefixes?uri=http://www.localhost.org/newuri1
```
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
+```
+will return http://www.localhost.org/uri1.
+
+A POST request
+```
+http://localhost:port/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
Review Comment:
```suggestion
http://localhost:port/dataset/prefixes?prefix=prefix1&uri=http://www.localhost.org/newuri1
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] prefixes-service documentation [jena-site]
Posted by "afs (via GitHub)" <gi...@apache.org>.
afs merged PR #188:
URL: https://github.com/apache/jena-site/pull/188
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] prefixes-service documentation [jena-site]
Posted by "rvesse (via GitHub)" <gi...@apache.org>.
rvesse commented on code in PR #188:
URL: https://github.com/apache/jena-site/pull/188#discussion_r1678993517
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
Review Comment:
The prefixes service is going to be associated with a dataset so shouldn't the example base URL be `http://localhost:port/dataset/prefix` ?
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
Review Comment:
The prefixes service is going to be associated with a dataset so shouldn't the example base URL be `http://localhost:port/dataset/prefixes` ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] prefixes-service documentation [jena-site]
Posted by "afs (via GitHub)" <gi...@apache.org>.
afs commented on code in PR #188:
URL: https://github.com/apache/jena-site/pull/188#discussion_r1681592462
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,107 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
+It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
+and also read-write access which adds the ability to add and delete prefix entries.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 2 parameters: prefix and uri.
+The fetch request is an HTTP GET and the update operation gets invoked
+via HTTP POST, and delete uses HTTP DELETE.
+
+### FetchURI
+If only the prefix parameter is provided and the uri is null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the prefix is null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If both prefix and uri are provided, the prefix-uri pair will be
+added to the dataset. If the prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Delete
+The delete operation is performed when the prefix parameter is provided to the HTTP DELETE. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
+
+If any of the arguments is not valid, (the [prefix](https://www.w3.org/TR/rdf12-turtle/#grammar-production-PN_PREFIX)
+and [URI](https://www.rfc-editor.org/rfc/rfc3986) don't have the correct syntax) the server returns 400,
+it does so also when the url string is not formed correctly, for example when the parameter names are incorrect.
+
+## Example
+
+For a server running on localhost using an example dataset
+
+| prefix | uri |
+|---------|-------------------------------|
+| prefix1 | http://www.localhost.org/uri1 |
+| prefix2 | http://www.localhost.org/uri2 |
+
+the following HTTP GET request
+```
+http://localhost:port/prefixes?prefix=prefix1
Review Comment:
Done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] prefixes-service documentation [jena-site]
Posted by "afs (via GitHub)" <gi...@apache.org>.
afs commented on code in PR #188:
URL: https://github.com/apache/jena-site/pull/188#discussion_r1676229356
##########
source/documentation/.DS_Store:
##########
Review Comment:
This should be removed.
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,108 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and remove functionalities
+for 3 different implementations of prefix-namespace storage: MapStorage , which is a Java Map data structure,
+RDFStorage - a DatasetGraph, and PrefixStorage, which uses a DatasetGraph's PrefixMap.
+
+## Operations
+
+The service supports fetch, remove and update operations on prefixes.
+When making requests to the API the url can have 3 parameters: prefix, uri, and prefixToRemove.
+The fetch request is an HTTP GET and the update and remove operations get invoked
+via HTTP POST.
+
+### FetchURI
+If only the prefix parameter is provided and the rest are null,
+the service will perform a fetch operation and return the corresponding URI.
+If no such prefix exists in the database the operation returns an empty String.
+
+### FetchPrefix
+If only the URI parameter is provided and the rest are null,
+the service will perform a fetch operation and return the corresponding prefixes in a JsonArray.
+If no such prefix exists in the database the operation returns an empty String.
+
+### GetAll
+A HTTP GET with no parameters returns all the prefix-URI pairs present in the dataset in a JsonArray.
+
+### Update
+If only the prefixToRemove parameter is left null, the provided prefix-uri pair will be
+added to the dataset. If the provided prefix already exists in the database, the pair will be overwritten.
+In case the namespace already exists with a different prefix, the pair will be added to the dataset.
+
+### Remove
+The remove operation is performed when only the prefixToRemove parameters is provided
+and the other parameters are null. It removes the prefix-namespace pair matching the provided
+prefix. The operation is considered successful when the request is correctly formed
+even if the prefix doesn't exist in the database.
Review Comment:
This needs updating because DELETE is now used instead of `prefixToRemove`.
##########
source/documentation/fuseki2/prefixes-service.md:
##########
@@ -0,0 +1,108 @@
+# Prefixes Service
+
+## Overview
+The prefix service provides prefix lookup, update and remove functionalities
+for 3 different implementations of prefix-namespace storage: MapStorage , which is a Java Map data structure,
+RDFStorage - a DatasetGraph, and PrefixStorage, which uses a DatasetGraph's PrefixMap.
Review Comment:
Might be better to focus on the form available to be configured - the PrefixMap of a DatasetGraph.
```suggestion
The prefix service provides prefix lookup, update and delete functionality on a collection of prefixes.
It provides a read access endpoint to look up a prefix name and to look up an URI to get prefixes for a URI
and also read-write access which adds the ability to add and delete prefix entries.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@jena.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org