{
"info": {
"author": "Albert Mero\u00c3\u00b1o",
"author_email": "albert.merono@vu.nl",
"bugtrack_url": null,
"classifiers": [],
"description": "![](\"https://raw.githubusercontent.com/CLARIAH/grlc/master/src/static/grlc_logo_01.png\")
\n\n[](https://gitter.im/grlc/Lobby#)\n[](https://zenodo.org/badge/latestdoi/46131212)\n[](https://travis-ci.org/CLARIAH/grlc)\n\n\ngrlc, the git repository linked data API constructor, automatically builds Web APIs using SPARQL queries stored in git repositories. http://grlc.io/\n\n**Contributors:**\t[Albert Mero\u00f1o](https://github.com/albertmeronyo), [Rinke Hoekstra](https://github.com/RinkeHoekstra), [Carlos Mart\u00ednez](https://github.com/c-martinez)\n\n**Copyright:**\tAlbert Mero\u00f1o, VU University Amsterdam \n**License:**\tMIT License (see [LICENSE.txt](LICENSE.txt))\n\n## What is grlc ?\ngrlc is a lightweight server that takes SPARQL queries curated in GitHub repositories, and translates them to Linked Data Web APIs. This enables universal access to Linked Data. Users are not required to know SPARQL to query their data, but instead can access a web API.\n\n## Quick tutorial\nFor a quick usage tutorial check out our wiki walkthrough [here](https://github.com/CLARIAH/grlc/wiki/Quick-tutorial)\n\n## Features\n\n- Request parameter mappings into SPARQL: grlc is compliant with [BASIL's convention](https://github.com/the-open-university/basil/wiki/SPARQL-variable-name-convention-for-WEB-API-parameters-mapping) on how to map GET/POST request parameters into SPARQL\n- Automatic, user customizable population of parameter values in swagger-ui's dropdown menus via SPARQL triple pattern querying\n- Parameter values as enumerations (i.e. closed lists of values that will fill a dropdown in the UI) can now also be specified in the query decorators to save endpoint requests (see [this example](https://github.com/albertmeronyo/lodapi/blob/master/houseType_params.rq))\n- Parameter default values can now also be indicated through decorators (see [this example](https://github.com/albertmeronyo/lodapi/blob/master/dbpedia_test.rq))\n- URL-based content negotiation: you can request for specific content types by attaching them to the operation request URL, e.g. [http://localhost:8088/CEDAR-project/Queries/residenceStatus_all.csv](http://localhost:8088/CEDAR-project/Queries/residenceStatus_all.csv) will request for results in CSV\n- Pagination of API results, as per the `pagination` decorator and [GitHub's API Pagination Traversal](https://developer.github.com/guides/traversing-with-pagination/)\n- Docker images in Docker Hub for easy deployment\n- Compatibility with [Linked Data Fragments](http://linkeddatafragments.org/) servers, RDF dumps, and HTML+RDFa files\n- **[NEW]** grlc integrates now [SPARQLTransformer](https://github.com/D2KLab/py-sparql-transformer), allowing the use of queries in JSON (see [this example](https://github.com/albertmeronyo/lodapi/blob/master/dbpedia_test_json.json)).\n- Generation of provenance in [PROV](https://www.w3.org/TR/prov-primer/) of both the repo history (via [Git2PROV](https://github.com/IDLabResearch/Git2PROV)) and grlc's activity additions\n- Commit-based API versioning that's coherent with the repo versioning with git hashes\n- SPARQL endpoint address can be set at the query level, repository level, and now also as a query **parameter**. This makes your APIs endpoint agnostic, and enables for generic and transposable queries!\n- CONSTRUCT queries are now mapped automatically to GET requests, accept parameters in the WHERE clause, and return content in ``text/turtle`` or ``application/ld+json``\n- INSERT DATA queries are now mapped automatically to POST requests. Support is limited to queries with no WHERE clause, and parameters are always expected to be values for ``g`` (named graph where to insert the data) and ``data`` (with the triples to insert, in ``ntriples`` format). The INSERT query pattern is so far static, as defined in [static.py](https://github.com/CLARIAH/grlc/blob/master/src/static.py#L61). Only tested with Virtuoso.\n\n## Install and run\n\nRunning via [docker](https://www.docker.com/) is the easiest and preferred form of deploying grlc. You'll need a working installation of [docker](https://www.docker.com/) and [docker-compose](https://docs.docker.com/compose/). To deploy grlc, just pull the latest image from Docker hub, and run docker compose with a `docker-compose.yml` that suits your needs (an [example](docker-compose.default.yml) is provided in the root directory):\n\n\ngit clone https://github.com/CLARIAH/grlc\ncd grlc\ndocker pull clariah/grlc\ndocker-compose -f docker-compose.default.yml up\n
\n\nTo run directly from Docker Hub it is sufficient to do:\n```\ndocker run --rm -p 8088:80 -e GRLC_SERVER_NAME=grlc.io -e GRLC_GITHUB_ACCESS_TOKEN=xxx -e GRLC_SPARQL_ENDPOINT=http://dbpedia.org/sparql -e DEBUG=true clariah/grlc\n```\n\n(You can omit the first two commands if you just copy [this file](docker-compose.default.yml) somehwere in your filesystem)\nIf you use the supplied `docker-compose.default.yml` your grlc instance will be available at http://localhost:8001\n\nIf you want your grlc instance to forward queries to a different service than `grlc.io`, edit the `GRLC_SERVER_NAME` variable in your `docker-compose.yml` or `docker-compose.default.yml` file.\n\nIn order for grlc to communicate with GitHub, you'll need to tell grlc what your access token is:\n\n1. Get a GitHub personal access token. In your GitHub's profile page, go to _Settings_, then _Developer settings_, _Personal access tokens_, and _Generate new token_\n2. You'll get an access token string, copy it and save it somewhere safe (GitHub won't let you see it again!)\n3. Edit your `docker-compose.yml` or `docker-compose.default.yml` file, and paste this token as value of the environment variable GRLC_GITHUB_ACCESS_TOKEN\n\nIf you want to run grlc at system boot as a service, you can find example upstart scripts at [upstart/](upstart/grlc-docker.conf)\n\n### Alternative install methods\n\nThrough these you'll miss some cool docker bundled features (like nginx-based caching). We provide these alternatives just for testing, development scenarios, or docker compatibility reasons.\n\n#### Prerequisites\n- Python3\n- development files:\n\n```bash\nsudo apt-get install libevent-dev python-all-dev\n```\n\n#### pip\n\nIf you want to use grlc as a library, you'll find it useful to install via `pip`.\n\n\npip install grlc\ngrlc-server\n
\n\nMore details can be found at [grlc's PyPi page](https://pypi.python.org/pypi/grlc) (thanks to [c-martinez](https://github.com/c-martinez)!).\n\n#### Flask application\n\nYou can run grlc natively as follows:\n```\ngunicorn -c gunicorn_config.py src.server:app\n```\n\n**Note:** Since `gunicorn` does not work under Windows, you can use `waitress` instead:\n```\nwaitress-serve --port=8088 src.server:app\n```\n\nYou can also find an example [here](https://github.com/CLARIAH/grlc/blob/master/docker-assets/entrypoint.sh#L24)\n\n## Usage\n\ngrlc assumes a GitHub repository (support for general git repos is on the way) where you store your SPARQL queries as .rq files (like in [this one](https://github.com/CEDAR-project/Queries)). grlc will create an API operation per such a SPARQL query/.rq file.\n\nIf you're seeing this, your grlc instance is up and running, and ready to build APIs. Assuming you got it running at http://localhost:8088/ and your queries are at https://github.com/CEDAR-project/Queries, just point your browser to the following locations:\n\n- To request the swagger spec of your API, http://localhost:8088/api/username/repo/spec, e.g. [http://localhost:8088/api/CEDAR-project/Queries/spec](http://localhost:8088/api/CEDAR-project/Queries/spec) or [http://localhost:8088/api/CLARIAH/wp4-queries/spec](http://localhost:8088/api/CLARIAH/wp4-queries/spec)\n- To request the api-docs of your API swagger-ui style, http://localhost:8088/api/username/repo/api-docs, e.g. [http://localhost:8088/api/CEDAR-project/Queries/api-docs](http://localhost:8088/api/CEDAR-project/Queries/api-docs) or [http://localhost:8088/api/CLARIAH/wp4-queries/api-docs](http://localhost:8088/api/CLARIAH/wp4-queries/api-docs)\n\nBy default grlc will direct your queries to the DBPedia SPARQL endpoint. To change this either:\n* Add a `endpoint` parameter to your request: 'http://grlc.io/user/repo/query?endpoint=http://sparql-endpoint/'. You can add a `#+ endpoint_in_url: False` decorator if you DO NOT want to see the `endpoint` parameter in the swagger-ui of your API.\n* Add a `#+ endpoint:` decorator in the first comment block of the query text (preferred, see below)\n* Add the URL of the endpoint on a single line in an `endpoint.txt` file within the GitHub repository that contains the queries.\n* Or you can directly modify the grlc source code (but it's nicer if the queries are self-contained)\n\nThat's it!\n\n### Example APIs\n\nCheck these out:\n\n- http://grlc.io/api/CLARIAH/wp4-queries-hisco/\n- http://grlc.io/api/albertmeronyo/lodapi/\n- http://grlc.io/api/albertmeronyo/lsq-api\n\nYou'll find the sources of these and many more in [GitHub](https://github.com/search?o=desc&q=endpoint+summary+language%3ASPARQL&s=indexed&type=Code&utf8=%E2%9C%93)\n\n## Decorator syntax\nA couple of SPARQL comment embedded decorators are available to make your swagger-ui look nicer (note all comments start with #+ and the use of `':'` is restricted to list-representations and cannot be used in the summary text):\n\n- To specify a query-specific endpoint, #+ endpoint: http://example.com/sparql.\n- To indicate the HTTP request method, #+ method: GET.\n- To paginate the results in e.g. groups of 100, #+ pagination: 100.\n- To create a summary of your query/operation, #+ summary: This is the summary of my query/operation\n- To assign tags to your query/operation,\n #+ tags:\n #+ - firstTag\n #+ - secondTag
\n- To indicate which parameters of your query/operation should get enumerations (and get dropdown menus in the swagger-ui) using values from the SPARQL endpoint,\n #+ enumerate:\n #+ - var1\n #+ - var2
\n- These parameters can also be hard-coded into the query decorators to save endpoint requests and speed up the API generation:\n#+ enumerate:\n#+ - var1:\n#+ - value1\n#+ - value2
\n\n Notice that these should be plain variable names without SPARQL/BASIL conventions (so `var1` instead of `?_var1_iri`)\n\nSee examples at [https://github.com/albertmeronyo/lodapi](https://github.com/albertmeronyo/lodapi).\n\nUse [this GitHub search](https://github.com/search?q=endpoint+summary+language%3ASPARQL&type=Code&utf8=%E2%9C%93) to see examples from other users of grlc.\n\n## Contribute!\n\ngrlc needs **you** to continue bringing Semantic Web content to developers, applications and users. No matter if you are just a curious user, a developer, or a researcher; there are many ways in which you can contribute:\n\n- File in bug reports\n- Request new features\n- Set up your own environment and start hacking\n\nCheck our [contributing](CONTRIBUTING.md) guidelines for these and more, and join us today!\n\nIf you cannot code, that's no problem! There's still plenty you can contribute:\n\n- Share your experience at using grlc in Twitter (mention the handler **@grlcldapi**)\n- If you are good with HTML/CSS, [let us know](mailto:albert.merono@vu.nl)\n\n## Related tools\n\n- [SPARQL2Git](https://github.com/albertmeronyo/SPARQL2Git) is a Web interface for editing SPARQL queries and saving them in GitHub as grlc APIs.\n- [grlcR](https://github.com/CLARIAH/grlcR) is a package for R that brings Linked Data into your R environment easily through grlc.\n- [Hay's tools](https://tools.wmflabs.org/hay/directory/#/showall) lists grlc as a Wikimedia-related tool :-)\n\n## This is what grlc users are saying\n\n- [Flavour your Linked Data with grlc](https://blog.esciencecenter.nl/flavour-your-linked-data-with-garlic-98bfbb358e06), by Carlos Martinez\n- [Egon Willighagen's blog](http://chem-bla-ics.blogspot.com/2018/07/converting-any-sparql-endpoint-to.html)\n\n## Academic publications\n\n- Albert Mero\u00f1o-Pe\u00f1uela, Rinke Hoekstra. \u201cgrlc Makes GitHub Taste Like Linked Data APIs\u201d. The Semantic Web \u2013 ESWC 2016 Satellite Events, Heraklion, Crete, Greece, May 29 \u2013 June 2, 2016, Revised Selected Papers. LNCS 9989, pp. 342-353 (2016). ([PDF](https://link.springer.com/content/pdf/10.1007%2F978-3-319-47602-5_48.pdf))\n- Albert Mero\u00f1o-Pe\u00f1uela, Rinke Hoekstra. \u201cSPARQL2Git: Transparent SPARQL and Linked Data API Curation via Git\u201d. In: Proceedings of the 14th Extended Semantic Web Conference (ESWC 2017), Poster and Demo Track. Portoroz, Slovenia, May 28th \u2013 June 1st, 2017 (2017). ([PDF](https://www.albertmeronyo.org/wp-content/uploads/2017/04/sparql2git-transparent-sparql-4.pdf))\n- Albert Mero\u00f1o-Pe\u00f1uela, Rinke Hoekstra. \u201cAutomatic Query-centric API for Routine Access to Linked Data\u201d. In: The Semantic Web \u2013 ISWC 2017, 16th International Semantic Web Conference. Lecture Notes in Computer Science, vol 10587, pp. 334-339 (2017). ([PDF](https://www.albertmeronyo.org/wp-content/uploads/2017/07/ISWC2017_paper_430.pdf))\n\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/CLARIAH/grlc",
"keywords": "",
"license": "Copyright 2017 Albert Mero\u00c3\u00b1o",
"maintainer": "",
"maintainer_email": "",
"name": "grlc",
"package_url": "https://pypi.org/project/grlc/",
"platform": "",
"project_url": "https://pypi.org/project/grlc/",
"project_urls": {
"Homepage": "https://github.com/CLARIAH/grlc"
},
"release_url": "https://pypi.org/project/grlc/1.3.0/",
"requires_dist": [
"Flask (==1.0.2)",
"Flask-Cors (==3.0.6)",
"gevent (==1.4.0)",
"greenlet (==0.4.15)",
"html5lib (==1.0.1)",
"isodate (==0.5.4)",
"itsdangerous (==1.1.0)",
"keepalive (==0.5)",
"MarkupSafe (==0.23)",
"pyaml (==18.11.0)",
"pyparsing (==2.0.7)",
"PyYAML (==4.2b1)",
"rdflib (==4.2.2)",
"rdflib-jsonld (==0.4.0)",
"requests (==2.20.0)",
"six (==1.11.0)",
"simplejson (==3.16.0)",
"setuptools (>=38.6.0)",
"SPARQLTransformer (==1.6.10)",
"SPARQLWrapper (==1.8.2)",
"Werkzeug (==0.14.1)",
"PyGithub (==1.43.5)",
"pythonql3 (==0.9.61)",
"gunicorn (==19.6.0) ; sys_platform != \"win32\"",
"waitress (==1.1.0) ; sys_platform == \"win32\""
],
"requires_python": "",
"summary": "grlc, the git repository linked data API constructor",
"version": "1.3.0"
},
"last_serial": 5470716,
"releases": {
"1.0": [
{
"comment_text": "",
"digests": {
"md5": "ce50c2b30ea829b716720ad25620905e",
"sha256": "173546eaa55d729db007bf9b7d4e8b5d9c0dd0acc03336aa8fae98992b1238c7"
},
"downloads": -1,
"filename": "grlc-1.0.tar.gz",
"has_sig": false,
"md5_digest": "ce50c2b30ea829b716720ad25620905e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 888827,
"upload_time": "2017-02-07T16:38:39",
"url": "https://files.pythonhosted.org/packages/e4/f6/69426c9c49839bdabf54053ab51bb619d4e951f520f2d320205f9cbfa5d9/grlc-1.0.tar.gz"
}
],
"1.1": [
{
"comment_text": "",
"digests": {
"md5": "194bc21cf1cd6a4b2618d72b39bb9851",
"sha256": "d04ec9ac38b5ff0428c0db867a2739e060e6f42aec795c2d2df94135c5399b07"
},
"downloads": -1,
"filename": "grlc-1.1.tar.gz",
"has_sig": false,
"md5_digest": "194bc21cf1cd6a4b2618d72b39bb9851",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 891215,
"upload_time": "2018-02-02T12:40:24",
"url": "https://files.pythonhosted.org/packages/2d/06/8481c73e0696455ae9f4b94d3a38dbaf7648b9bc3cf64b8f3ecf436e6a8a/grlc-1.1.tar.gz"
}
],
"1.2.0": [
{
"comment_text": "",
"digests": {
"md5": "5b43c5acf8dd0adfaf66885dac9999af",
"sha256": "74ad1297f72155dacdb42b6672875f9a0f041fe07da8e78c9f89f175953b222c"
},
"downloads": -1,
"filename": "grlc-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b43c5acf8dd0adfaf66885dac9999af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 948092,
"upload_time": "2018-10-17T12:26:25",
"url": "https://files.pythonhosted.org/packages/bf/8e/e4bc8aea9413f5ea71d21d2494775267ac45a865c01c95dd0537c631c955/grlc-1.2.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "283102416175ac3c195846e7394c5d26",
"sha256": "a8ca9ae256002ae869d257b00a6f00bba2505e07834a634ddf757ce3886a8e74"
},
"downloads": -1,
"filename": "grlc-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "283102416175ac3c195846e7394c5d26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 919473,
"upload_time": "2018-10-17T12:26:27",
"url": "https://files.pythonhosted.org/packages/ed/06/b5abc1bb6a221bd1727cac1f247fd14868e435ec3ddb0f6c8b91d04620b4/grlc-1.2.0.tar.gz"
}
],
"1.2.1": [
{
"comment_text": "",
"digests": {
"md5": "4857b8917125331f35af8e27d0389d1b",
"sha256": "63e45260d44a79768236439a2c727c8a69476378ab4aa07dc961312cae3524df"
},
"downloads": -1,
"filename": "grlc-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4857b8917125331f35af8e27d0389d1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 73440,
"upload_time": "2019-02-07T16:08:06",
"url": "https://files.pythonhosted.org/packages/7f/22/3c6b33dd8c932aba678af709b16128575ed274e617e3ff534be6d3d0aa71/grlc-1.2.1-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "49335eebe688bea3c177db2ed67b89ed",
"sha256": "4872c6326a2616b1a3a6611a8d23a3a8e0a0ce8293088959eb24860f86ac3ed7"
},
"downloads": -1,
"filename": "grlc-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "49335eebe688bea3c177db2ed67b89ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 69096,
"upload_time": "2019-02-07T16:08:08",
"url": "https://files.pythonhosted.org/packages/1e/e7/1267d5d42ce6185026c591eb9ac61967569a573501b93856fffedbe03e26/grlc-1.2.1.tar.gz"
}
],
"1.3.0": [
{
"comment_text": "",
"digests": {
"md5": "a150e71234e13d661cdf6e4b047c058a",
"sha256": "65ebd73ae31a1caa216f08cae3968bba4fc126f3219686408c5038715bf9a78d"
},
"downloads": -1,
"filename": "grlc-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a150e71234e13d661cdf6e4b047c058a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 74493,
"upload_time": "2019-07-01T11:45:57",
"url": "https://files.pythonhosted.org/packages/e5/3c/007989f18df88726e78b2a95a74bc83bd7b2dae328e11ff571cdb51a7d3e/grlc-1.3.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "2ede264e4a9c8b56830cd477dacd7c40",
"sha256": "9f797e84fc3f6322c6583ce05227a84c99e3019606531748e2d39c4d359031c3"
},
"downloads": -1,
"filename": "grlc-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "2ede264e4a9c8b56830cd477dacd7c40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 70235,
"upload_time": "2019-07-01T11:45:59",
"url": "https://files.pythonhosted.org/packages/2c/bb/bdb644240eb567036c933fa16c80797675d7ebd7d7b87eaa669a56419db7/grlc-1.3.0.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "a150e71234e13d661cdf6e4b047c058a",
"sha256": "65ebd73ae31a1caa216f08cae3968bba4fc126f3219686408c5038715bf9a78d"
},
"downloads": -1,
"filename": "grlc-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a150e71234e13d661cdf6e4b047c058a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 74493,
"upload_time": "2019-07-01T11:45:57",
"url": "https://files.pythonhosted.org/packages/e5/3c/007989f18df88726e78b2a95a74bc83bd7b2dae328e11ff571cdb51a7d3e/grlc-1.3.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "2ede264e4a9c8b56830cd477dacd7c40",
"sha256": "9f797e84fc3f6322c6583ce05227a84c99e3019606531748e2d39c4d359031c3"
},
"downloads": -1,
"filename": "grlc-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "2ede264e4a9c8b56830cd477dacd7c40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 70235,
"upload_time": "2019-07-01T11:45:59",
"url": "https://files.pythonhosted.org/packages/2c/bb/bdb644240eb567036c933fa16c80797675d7ebd7d7b87eaa669a56419db7/grlc-1.3.0.tar.gz"
}
]
}