Commit a2ab9527 authored by jess 3jane's avatar jess 3jane

docs/http-api: Update docs with example session

parent fb19e152
Pipeline #573 passed with stages
in 9 minutes and 15 seconds
# Summary
[Introduction](./intro.md)
- [Topics](./topics/_intro.md)
- [Authentication](./topics/authentication.md)
- [Cookies](./topics/cookies.md)
- [JSON:API](./topics/jsonapi.md)
- [Services](./topics/services.md)
- [Entities](./entities/_intro.md)
- [`success`](./entities/success.md)
- [`user`](./entities/user.md)
- [`user_auth`](./entities/user_auth.md)
- [`user_grant`](./entities/user_grant.md)
- [Endpoints](./endpoints/_intro.md)
- [`login`](./endpoints/login.md)
- [`logout`](./endpoints/logout.md)
[Example Session](./example_session.md)
# So You Want To Use the HTTP API
This is a basic tutorial covering how to get started with the qaul.net HTTP API
The API is built on the principles of [JSON:API](https://jsonapi.org/format/) so while not
strictly nessicary it is highly encouraged you read the spec before starting.
Before we can do anything we need a user and that means creating a new `secret`
```
curl -i \
-H "Content-Type: application/vnd.api+json" \
-d '{
"data": {
"type": "secret",
"attributes": {
"value": "MyFairSecret"
}
}
}' \
"http://0.0.0.0:9090/api/secrets"
```
which will return something like
```
{
"data": {
"id": "2a6463711f0e149a0262a34fc79b9e16",
"type": "secret",
"relationships": {
"user": {
"data": {
"id": "2a6463711f0e149a0262a34fc79b9e16",
"type": "user"
}
}
},
"links": {
"self": "/api/secrets/2a6463711f0e149a0262a34fc79b9e16"
}
}
}
```
The `id` field of `data` is our user id, `2a6463711f0e149a0262a34fc79b9e16`.
Now we should get a `grant` for our user, which will be used to authenticate our
application to the API.
```
curl -i \
-H "Content-Type: application/vnd.api+json" \
-d '{
"data": {
"type": "grant",
"attributes": {
"secret": "MyFairSecret"
},
"relationships": {
"user": {
"data": {
"type": "user",
"id": "2a6463711f0e149a0262a34fc79b9e16"
}
}
}
}
}' \
"http://0.0.0.0:9090/api/grants"
```
Notice that we provide the id of the user we're trying to get a grant for as a relationship.
This will return something like:
```
{
"data": {
"id": "hZ4g3IGKsGlZarvJr4EYGSaMtBGCqbTv13g47KuKQawGG9p2PHPOuuG6DDv05AGjb5090a3wW6YE_-iTHxgmkpeLeYv7DOILj9_mNd6kcGmrV3X-UiBxIIXIWymV-yLhbnY5J9B-FEZsOPJNpzd9rNAe8SKV_5v2Y1jPpqERYBJcLAwd2NQwz531t1Oq7i8j3H2weDNOZijc6HN-B7_DTUSudKIPbUx7g1UnLlq4J22ezwFe8KHmA12ANDfCgzT2GAMjGgB-B0QvicvsCP-6TemCHSF0fctFoGuYRX25DALon0pf8N0K8kGMZtV-WongJi0ns2gAfbWl9JjAx1ssfw==",
"type": "grant",
"relationships": {
"user": {
"data": {
"id": "2a6463711f0e149a0262a34fc79b9e16",
"type": "user"
}
}
},
"links": {
"self": "/api/grants/hZ4g3IGKsGlZarvJr4EYGSaMtBGCqbTv13g47KuKQawGG9p2PHPOuuG6DDv05AGjb5090a3wW6YE_-iTHxgmkpeLeYv7DOILj9_mNd6kcGmrV3X-UiBxIIXIWymV-yLhbnY5J9B-FEZsOPJNpzd9rNAe8SKV_5v2Y1jPpqERYBJcLAwd2NQwz531t1Oq7i8j3H2weDNOZijc6HN-B7_DTUSudKIPbUx7g1UnLlq4J22ezwFe8KHmA12ANDfCgzT2GAMjGgB-B0QvicvsCP-6TemCHSF0fctFoGuYRX25DALon0pf8N0K8kGMZtV-WongJi0ns2gAfbWl9JjAx1ssfw=="
}
}
}
```
The `id` field of `data` here is our grant. We will pass this in the future as a bearer auth token.
Let's give our user a name and fill out their profile a bit:
```
curl -i \
-X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer hZ4g3IGKsGlZarvJr4EYGSaMtBGCqbTv13g47KuKQawGG9p2PHPOuuG6DDv05AGjb5090a3wW6YE_-iTHxgmkpeLeYv7DOILj9_mNd6kcGmrV3X-UiBxIIXIWymV-yLhbnY5J9B-FEZsOPJNpzd9rNAe8SKV_5v2Y1jPpqERYBJcLAwd2NQwz531t1Oq7i8j3H2weDNOZijc6HN-B7_DTUSudKIPbUx7g1UnLlq4J22ezwFe8KHmA12ANDfCgzT2GAMjGgB-B0QvicvsCP-6TemCHSF0fctFoGuYRX25DALon0pf8N0K8kGMZtV-WongJi0ns2gAfbWl9JjAx1ssfw==" \
-d '{
"data": {
"id": "2a6463711f0e149a0262a34fc79b9e16",
"type": "user",
"attributes": {
"display_name": "tester",
"real_name": "Tester McTesterson III",
"bio": {
"gender": "I would really rather not",
"shirt color": "red"
}
}
}
}' \
"http://0.0.0.0:9090/api/users/2a6463711f0e149a0262a34fc79b9e16"
```
which returns the updated user record
```
{
"data": {
"id": "2a6463711f0e149a0262a34fc79b9e16",
"type": "user",
"attributes": {
"bio": {
"gender": "I would really rather not",
"shirt color": "red"
},
"display_name": "tester",
"real_name": "Tester McTesterson III",
"services": []
},
"relationships": {
"secret": {
"data": {
"id": "2a6463711f0e149a0262a34fc79b9e16",
"type": "secret"
}
}
},
"links": {
"self": "/api/users/2a6463711f0e149a0262a34fc79b9e16"
}
}
}
```
Let's say our user has met a new friend with id `f7335eb601789ddbe0cd76f6915eb3fe`. They perform
a look up to find the user's profile:
```
curl -i \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer hZ4g3IGKsGlZarvJr4EYGSaMtBGCqbTv13g47KuKQawGG9p2PHPOuuG6DDv05AGjb5090a3wW6YE_-iTHxgmkpeLeYv7DOILj9_mNd6kcGmrV3X-UiBxIIXIWymV-yLhbnY5J9B-FEZsOPJNpzd9rNAe8SKV_5v2Y1jPpqERYBJcLAwd2NQwz531t1Oq7i8j3H2weDNOZijc6HN-B7_DTUSudKIPbUx7g1UnLlq4J22ezwFe8KHmA12ANDfCgzT2GAMjGgB-B0QvicvsCP-6TemCHSF0fctFoGuYRX25DALon0pf8N0K8kGMZtV-WongJi0ns2gAfbWl9JjAx1ssfw==" \
"http://0.0.0.0:9090/api/users/f7335eb601789ddbe0cd76f6915eb3fe"
```
which returns
```
{
"data": {
"id": "f7335eb601789ddbe0cd76f6915eb3fe",
"type": "user",
"attributes": {
"bio": {
"gender": "yes please"
},
"display_name": "friend",
"real_name": "Friendly, First of Their Name",
"services": []
},
"relationships": {
"secret": {
"data": {
"id": "f7335eb601789ddbe0cd76f6915eb3fe",
"type": "secret"
}
}
},
"links": {
"self": "/api/users/f7335eb601789ddbe0cd76f6915eb3fe"
}
}
}
```
The user is done with this session so they decide to log out:
```
curl -i \
-X DELETE \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer hZ4g3IGKsGlZarvJr4EYGSaMtBGCqbTv13g47KuKQawGG9p2PHPOuuG6DDv05AGjb5090a3wW6YE_-iTHxgmkpeLeYv7DOILj9_mNd6kcGmrV3X-UiBxIIXIWymV-yLhbnY5J9B-FEZsOPJNpzd9rNAe8SKV_5v2Y1jPpqERYBJcLAwd2NQwz531t1Oq7i8j3H2weDNOZijc6HN-B7_DTUSudKIPbUx7g1UnLlq4J22ezwFe8KHmA12ANDfCgzT2GAMjGgB-B0QvicvsCP-6TemCHSF0fctFoGuYRX25DALon0pf8N0K8kGMZtV-WongJi0ns2gAfbWl9JjAx1ssfw==" \
"http://0.0.0.0:9090/api/grants/hZ4g3IGKsGlZarvJr4EYGSaMtBGCqbTv13g47KuKQawGG9p2PHPOuuG6DDv05AGjb5090a3wW6YE_-iTHxgmkpeLeYv7DOILj9_mNd6kcGmrV3X-UiBxIIXIWymV-yLhbnY5J9B-FEZsOPJNpzd9rNAe8SKV_5v2Y1jPpqERYBJcLAwd2NQwz531t1Oq7i8j3H2weDNOZijc6HN-B7_DTUSudKIPbUx7g1UnLlq4J22ezwFe8KHmA12ANDfCgzT2GAMjGgB-B0QvicvsCP-6TemCHSF0fctFoGuYRX25DALon0pf8N0K8kGMZtV-WongJi0ns2gAfbWl9JjAx1ssfw=="
```
......@@ -3,6 +3,11 @@
This guide documents the qaul.net HTTP Api. The Api primarily speaks [JSON:API](https://jsonapi.org/)
which has its own [Documentation](https://jsonapi.org/format/).
This documentation is **highly out of date** and will be updated in the future. If you wish to use
the HTTP Api in the mean time I recommend you check out the [Example Session] for an example
of the Api in action. If you have any questions, please feel free to ping me, jess3jane, in the
IRC channel.
This guide is divided into three sections:
- [Topics] which provides a structured walkthrough of some of the core components of the Api
......@@ -12,3 +17,4 @@ This guide is divided into three sections:
[Topics]: /topics/_intro.html
[Entities]: /entities/_intro.html
[Endpoints]: /endpoints/_intro.html
[Example Session]: /example_session.md
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment