Skip to content

Commit 2952cd7

Browse files
indeyetsindeyets
committed
moved API-docs to separate file. documented SPARQL-endpoint
1 parent 501e6a4 commit 2952cd7

File tree

2 files changed

+144
-130
lines changed

2 files changed

+144
-130
lines changed

‎API.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
## Introspection
2+
3+
### predicates
4+
5+
API endpoint: `https://api.grids.by/v1/predicates.json`
6+
7+
Parameters:
8+
9+
* `graph` [required, Read-access required]
10+
11+
Example query: `https://api.grids.by/v1/predicates.json?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fweb-apis`
12+
13+
OAuth signature is required.
14+
15+
Returns list of RDF-predicates, which are present in graph.
16+
17+
Valid responses are:
18+
19+
* 200 OK, `Content-type: application/json`, body is an array of URIs
20+
* 4xx — various errors
21+
22+
### values
23+
24+
API endpoint: `https://api.grids.by/v1/values.json`
25+
26+
Parameters:
27+
28+
* `graph` [required, Read-access required]
29+
* `predicate` [required]
30+
31+
Example query: `https://api.grids.by/v1/value.json?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fweb-apis&predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label`
32+
33+
OAuth signature is required.
34+
35+
Returns list of values, which correspond to the predicate given, in this graph.
36+
37+
Valid responses are:
38+
39+
* 200 OK, `Content-type: application/json`, body is an array of strings
40+
* 4xx — various errors
41+
42+
## Read data
43+
44+
### list
45+
46+
API endpoint: `https://api.grids.by/v1/list.json`
47+
48+
Parameters:
49+
50+
* `graph` [required, Read-access required]
51+
* you can use any number of `filters[n][predicate]=value` parameters to filter dataset (don't forget to "urlencode" them)
52+
53+
Example query: `https://api.grids.by/v1/list.json?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fweb-apis&filters%5B0%5D%5Bschema%3Aname%5D=BitBucket&filters%5B1%5D%5Bschema%3Aname%5D=GitHub`
54+
55+
If you're planning on passing a lot of parameters it's recommended to use POST and provide the parameters in the request body as a JSON (make sure to provide proper `Content-type` header):
56+
57+
```json
58+
{
59+
"graph":"http://grids.by/graphs/web-apis",
60+
"filters":[
61+
{"schema:name":"BitBucket"},
62+
{"schema:name":"123ContactForm"},
63+
]
64+
}
65+
```
66+
67+
OAuth signature is required.
68+
69+
Returns list of RDF-subjects, which have matching predicate/value pairs.
70+
71+
Valid responses are:
72+
73+
* 200 OK, `Content-type: application/json`, body is an array of URIs, which are "subjects" of the items
74+
* 4xx — various errors
75+
76+
### get
77+
78+
API endpoint: `https://api.grids.by/v1/get.json`
79+
80+
Parameters:
81+
82+
* `graph` [required, Read-access required]
83+
* `subject` [required]
84+
* `deeper` [optional, default=0; can be "0" or "1"]
85+
86+
Example query: `https://api.grids.by/v1/get.json?graph=http://grids.by/graphs/web-apis&subject=http://apis.io/Bing`
87+
88+
If you're planning on passing a lot of parameters it's recommended to use POST and provide the parameters in the request body as a JSON:
89+
```json
90+
{
91+
"graph":"http://grids.by/graphs/web-apis",
92+
"subject":"http://apis.io/Bing",
93+
"deeper":0
94+
}
95+
```
96+
97+
OAuth signature is required
98+
99+
Returns JSON-LD structure, which corresponds to requested graph/subject pair. Will give 1 additional level of depth, if `deeper=1` parameter is given.
100+
101+
Valid responses are:
102+
103+
* 200 OK, `Content-type: application/ld+json`
104+
* 4xx — various errors
105+
106+
## Write data
107+
108+
### append
109+
110+
API endpoint: `https://api.grids.by/v1/append`
111+
112+
Parameters:
113+
114+
* `graph` [required, Append- or Write-access is required]
115+
116+
Example query: `http://api.grids.by/v1/append?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fmovies`
117+
118+
This should be a POST request, POST body should contain the triples to import in Turtle or JSON-LD format with the appropriate headers `text/turtle` or `application/ld+json` respectively.
119+
120+
OAuth signature is required
121+
122+
Triples would be imported into requested graph (if application has enough permissions).
123+
124+
Check HTTP status code. Valid responses are:
125+
126+
* 200 OK, Content-type: plain/text, body has number of triples which were imported
127+
* 202 Accepted (we got the data, put it in queue, but it is not imported yet)
128+
* 400 Bad Request (required parameters are not set, or data is not valid syntactically)
129+
* 422 Unprocessable Entity (we can't import data you provided, for some reason. syntax is ok, but there is some semantic problem)
130+
* 4xx — various other errors
131+
132+
## Other
133+
134+
### SPARQL
135+
136+
API endpoint: `https://api.grids.by/v1/sparql`
137+
138+
Parameters:
139+
140+
* `default-graph-uri` [at least one required, **both** Read- and Write-access is required]
141+
* see [SPARQL 1.1 Protocol](http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/) for further details
142+
143+
OAuth signature is required

‎Developers Tutorial.md‎

Lines changed: 1 addition & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -28,133 +28,4 @@ Now, you have 5 pieces of information, which you'll need to hardcode into your a
2828

2929
## API
3030

31-
### Introspection
32-
33-
#### predicates
34-
35-
API endpoint: `https://api.grids.by/v1/predicates.json`
36-
37-
Parameters:
38-
39-
* `graph` [required]
40-
41-
Example query: `https://api.grids.by/v1/predicates.json?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fweb-apis`
42-
43-
OAuth signature is required.
44-
45-
Returns list of RDF-predicates, which are present in graph.
46-
47-
Valid responses are:
48-
49-
* 200 OK, `Content-type: application/json`, body is an array of URIs
50-
* 4xx — various errors
51-
52-
#### values
53-
54-
API endpoint: `https://api.grids.by/v1/values.json`
55-
56-
Parameters:
57-
58-
* `graph` [required]
59-
* `predicate` [required]
60-
61-
Example query: `https://api.grids.by/v1/value.json?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fweb-apis&predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label`
62-
63-
OAuth signature is required.
64-
65-
Returns list of values, which correspond to the predicate given, in this graph.
66-
67-
Valid responses are:
68-
69-
* 200 OK, `Content-type: application/json`, body is an array of strings
70-
* 4xx — various errors
71-
72-
### Read data
73-
74-
#### list
75-
76-
API endpoint: `https://api.grids.by/v1/list.json`
77-
78-
Parameters:
79-
80-
* `graph` [required]
81-
* you can use any number of `filters[n][predicate]=value` parameters to filter dataset (don't forget to "urlencode" them)
82-
83-
Example query: `https://api.grids.by/v1/list.json?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fweb-apis&filters%5B0%5D%5Bschema%3Aname%5D=BitBucket&filters%5B1%5D%5Bschema%3Aname%5D=GitHub`
84-
85-
If you're planning on passing a lot of parameters it's recommended to use POST and provide the parameters in the request body as a JSON (make sure to provide proper `Content-type` header):
86-
87-
```json
88-
{
89-
"graph":"http://grids.by/graphs/web-apis",
90-
"filters":[
91-
{"schema:name":"BitBucket"},
92-
{"schema:name":"123ContactForm"},
93-
]
94-
}
95-
```
96-
97-
OAuth signature is required.
98-
99-
Returns list of RDF-subjects, which have matching predicate/value pairs.
100-
101-
Valid responses are:
102-
103-
* 200 OK, `Content-type: application/json`, body is an array of URIs, which are "subjects" of the items
104-
* 4xx — various errors
105-
106-
#### get
107-
108-
API endpoint: `https://api.grids.by/v1/get.json`
109-
110-
Parameters:
111-
112-
* `graph` [required]
113-
* `subject` [required]
114-
* `deeper` [optional, default=0; can be "0" or "1"]
115-
116-
Example query: `https://api.grids.by/v1/get.json?graph=http://grids.by/graphs/web-apis&subject=http://apis.io/Bing`
117-
118-
If you're planning on passing a lot of parameters it's recommended to use POST and provide the parameters in the request body as a JSON:
119-
```json
120-
{
121-
"graph":"http://grids.by/graphs/web-apis",
122-
"subject":"http://apis.io/Bing",
123-
"deeper":0
124-
}
125-
```
126-
127-
OAuth signature is required
128-
129-
Returns JSON-LD structure, which corresponds to requested graph/subject pair. Will give 1 additional level of depth, if `deeper=1` parameter is given.
130-
131-
Valid responses are:
132-
133-
* 200 OK, `Content-type: application/ld+json`
134-
* 4xx — various errors
135-
136-
### Write data
137-
138-
#### append
139-
140-
API endpoint: `https://api.grids.by/v1/append`
141-
142-
Parameters:
143-
144-
* `graph` [required]
145-
146-
Example query: `http://api.grids.by/v1/append?graph=http%3A%2F%2Fgrids.by%2Fgraphs%2Fmovies`
147-
148-
This should be a POST request, POST body should contain the triples to import in Turtle or JSON-LD format with the appropriate headers `text/turtle` or `application/ld+json` respectively.
149-
150-
OAuth signature is required
151-
152-
Triples would be imported into requested graph (if application has enough permissions).
153-
154-
Check HTTP status code. Valid responses are:
155-
156-
* 200 OK, Content-type: plain/text, body has number of triples which were imported
157-
* 202 Accepted (we got the data, put it in queue, but it is not imported yet)
158-
* 400 Bad Request (required parameters are not set, or data is not valid syntactically)
159-
* 422 Unprocessable Entity (we can't import data you provided, for some reason. syntax is ok, but there is some semantic problem)
160-
* 4xx — various other errors
31+
API-description was moved into [separate document](API.md).

0 commit comments

Comments
 (0)