Proca Server API
Proca Server uses a GraphQL API at an endpoint /api
for a HTTP connection or /socket
for a WebSocket connection. You will need WebSocket to run subscription operations with GraphQL, however, for Proca Server the HTTP API is usually enough (currently there is 1 subscription operation).
If you develop for node, you can use @proca/api
library to create a configured GraphQL client (using urql
library).
GraphQL provides a discoverable API, which you can explore in the playground at /graphiql
endpoint (example), or using a GraphQL client of choice.
Authentication and security context
All operations run in some user context:
- Anonymous
- Authenticated - an User is assigned to the opration based on one of authentication methods, and optionally a current organisation - they form a security context.
authentication methods
Use Authorization
header to authenticate the operation. We support:
- HTTP Basic Auth header with email + password:
Authorization: Basic base64-encoded-user:password
- API token - generated by Proca Server for a user (create it with
resetApiToken
mutation):Authorization: API-XXXXXXX
- JWT token - if configured; tested with Zero Trust Proxy and GoTrue/Supabase:
Authorization: eyJWT-token-JWTJWTJWTJWTJWTJWTJWT
Errors
Errors are returned as a list of GraphQL errors, each consisting of a human readable message
, path
specifying which input value causes a problem, and extensions
object, which has a machine readable error code
.
Example query with basic authenticate
Consider this TypeScript code. It creates a connection using HTTP Basic Auth using helpers from @proca/api
library. Then it runs a query to fetch current, authenticated user. We recommend to use GraphQL Codegen to create a typed query documents from foo.graphql
files. This will provide you with typed responses from the API and ease unpacking returned objects.
import "cross-fetch/polyfill" // for missing fetch() in node...
import {httpLink, basicAuth} from '@proca/api'
const whoami = async (email : string, pwd : string) => {
const client = httpLink('https://api.proca.app', basicAuth({username: email, password: pwd}));
const query = `
query CurrentUserOrgs {
currentUser {
email roles { role org {name title} }
}
}`
const {data, error} = await client.query(query, {}).toPromise()
if (error?.graphQLErrors[0]?.extensions?.code === 'unauthorized') {
console.error("Bad credentials")
return
}
const myOrgs = data.currentUser.roles.map(({title})=>title).join(', ')
console.log(`I am ${data.currentUser.email}`)
console.log(`I am member of these orgs: ${myOrgs}`)
}