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-unsubscr...@jena.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
