sondahub

sondahub / Social API

Social: a fake social media API

A social network: users, posts, comments, likes and follows — the GraphQL one.

Eight hundred users, four thousand posts, eight thousand comments and the likes and follows between them. Deeply related, which is what GraphQL is for: a user, the user’s posts, each post’s comments and the comment authors in one query. 25,800 records in all, free over REST, GraphQL, OData, gRPC-Web, SOAP, JSON-RPC, Socket.IO, WebSocket and SSE — no key, no signup.

Connect

Base URL
https://api.sondahub.com/v1/social
OpenAPI 3
https://api.sondahub.com/v1/social/openapi.json
GraphQL
https://api.sondahub.com/v1/social/graphql
OData
https://api.sondahub.com/odata/social/
gRPC-Web
https://api.sondahub.com/grpc/sondahub.social.v1.SocialService
.proto
https://api.sondahub.com/v1/social/social.proto
SOAP WSDL
https://api.sondahub.com/soap/social?wsdl
JSON-RPC
https://api.sondahub.com/jsonrpc — social.getUser
XML-RPC
https://api.sondahub.com/xmlrpc
WebSocket
wss://api.sondahub.com/v1/social/ws
SSE
https://api.sondahub.com/v1/social/events
Socket.IO
https://api.sondahub.com/social — transports: ['websocket']
The data
users.json, posts.json, comments.json, likes.json, follows.json

In Sonda: Import → From a URL with the OpenAPI address and the whole API lands as a project, one request per operation with example bodies. No keys, no headers to add. More on each protocol.

Writes stick for whoever carries them. POST, PUT, PATCH and DELETE are validated, run through the real rules and answered as a real server would, and the answer carries X-Sondahub-Session: send that token back and the next request sees your write. The server keeps nothing — without the token the world is the seed again. The examples on this page share one session until you reload. More on sessions.
The API describes itself
curl https://api.sondahub.com/v1/social

Lists and filters

Every list answers { "data": [...], "meta": { "page", "limit", "total", "pages" } } with X-Total-Count and Link headers (next, prev, first, last). These options work on every collection and every nested route:

OptionMeaningExample
page, limitPaging, 1-based; limit 1–200, default 20. offset works too.?page=3&limit=50
sortComma list of fields, - for descending. Default id here.?sort=-id,id
field=valueEquals. Booleans as true/false, null for missing.?id=1
_ne _gt _gte _lt _lteNot equal and comparisons, on numbers, dates and strings.?id_gt=10
_likeContains, case-insensitive.?username_like=an
_inAny of a comma list.?id_in=1,2,3
_nulltrue: missing; false: present.?email_null=true
a.b=valueInside a JSON field, dotted.?media.kind=…
qSearch across the text fields.?q=alpine
fieldsOnly these fields back.?fields=id,username
expandEmbed related records.?expand=posts,comments
paging=cursor, cursorCursor paging: meta gains has_more, next_cursor and prev_cursor. starting_after / ending_before take an id, Stripe-style.?paging=cursor&limit=50
formatThe same answer as CSV, XML, YAML, NDJSON or MessagePack — or ask with Accept.?format=csv

A name that is not a field answers 400 and lists the fields. Writes answer 422 with one line per problem, 404 for a missing id, 405 with an Allow header for a verb a route does not take. Any request also takes chaos, a rate limit, an Idempotency-Key and problem+json errors, and any write a signed webhook.

users

Members. 800 records — the file, or the users API page with sample records.

FieldTypeNotes
idread-onlyintAssigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.
created_atread-onlydatetimeWhen the record was created (ISO 8601, UTC).
updated_atread-onlydatetimeWhen the record last changed.
usernamerequiredstringUnique handle.
display_namerequiredstring
emailstring
biotext
avatar_urlstringA generated SVG with the initials, served by the hub at this address.
locationstring
websitestring
verifiedbool
privatebool
followers_countread-onlyint
following_countread-onlyint
posts_countread-onlyint
joined_atdatetime

Relations: posts → the posts whose author_id is this user; comments → the comments whose author_id is this user; likes → the likes whose user_id is this user; followers → the follows whose followee_id is this user; following → the follows whose follower_id is this user. Use ?expand=posts,comments,likes,followers,following to embed them, or the nested routes.

Endpoints

GET/v1/social/usersA page, with every filter, sort, search, field and expand option.
POST/v1/social/usersCreate one: 201 with the record, its id, a Location header and the session token that keeps it; 422 names each field that is wrong.
GET/v1/social/users/{id}One record, with an ETag; If-None-Match earns a 304.
PATCH/v1/social/users/{id}Change the fields you send.
PUT/v1/social/users/{id}Replace the record; required fields must all be there.
DELETE/v1/social/users/{id}Answers 200 with what was removed (a real server’s 204 lives at /v1/utils/status/204); gone for the session.
GET/v1/social/users/{id}/postsIts posts, as a page with all the list options.
GET/v1/social/users/{id}/commentsIts comments, as a page with all the list options.
GET/v1/social/users/{id}/likesIts likes, as a page with all the list options.
GET/v1/social/users/{id}/followersIts follows, as a page with all the list options.
GET/v1/social/users/{id}/followingIts follows, as a page with all the list options.

Try it

List with a filter
curl "https://api.sondahub.com/v1/social/users?limit=3"
One record
curl https://api.sondahub.com/v1/social/users/1
Its posts
curl "https://api.sondahub.com/v1/social/users/1/posts?limit=5"
Create
curl -i -X POST https://api.sondahub.com/v1/social/users \
  -H "Content-Type: application/json" \
  -d '{"username":"camila_fernandez","display_name":"A display name"}'
Read it back: newest first (send the session token)
curl "https://api.sondahub.com/v1/social/users?sort=-id&limit=3" \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"
Change one field
curl -X PATCH https://api.sondahub.com/v1/social/users/1 \
  -H "Content-Type: application/json" \
  -d '{"username":"Changed username"}'
Delete the one you created
curl -X DELETE https://api.sondahub.com/v1/social/users/801 \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"

posts

What people write. hashtags is an array; filter with ?hashtags_like=coffee. 4,000 records — the file, or the posts API page with sample records.

POST fills defaults (public, empty hashtags, now) and bumps the author’s posts_count.
FieldTypeNotes
idread-onlyintAssigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.
created_atread-onlydatetimeWhen the record was created (ISO 8601, UTC).
updated_atread-onlydatetimeWhen the record last changed.
author_idrequiredint → users
bodyrequiredtext
hashtagsjson string[]
mediajson { kind, url, alt? }[]
visibilityenumpublic followers private
reply_to_idint → postsSet when the post is a reply.
likes_countread-onlyint
comments_countread-onlyint
reposts_countread-onlyint
languagestring
published_atdatetime
edited_atdatetime

Relations: author → one user through author_id; reply_to → one post through reply_to_id; comments → the comments whose post_id is this post; likes → the likes whose post_id is this post. Use ?expand=author,comments,likes,reply_to to embed them, or the nested routes.

Endpoints

GET/v1/social/postsA page, with every filter, sort, search, field and expand option.
POST/v1/social/postsCreate one: 201 with the record, its id, a Location header and the session token that keeps it; 422 names each field that is wrong.
GET/v1/social/posts/{id}One record, with an ETag; If-None-Match earns a 304.
PATCH/v1/social/posts/{id}Change the fields you send.
PUT/v1/social/posts/{id}Replace the record; required fields must all be there.
DELETE/v1/social/posts/{id}Answers 200 with what was removed (a real server’s 204 lives at /v1/utils/status/204); gone for the session.
GET/v1/social/posts/{id}/authorThe user this record points at.
GET/v1/social/posts/{id}/commentsIts comments, as a page with all the list options.
GET/v1/social/posts/{id}/likesIts likes, as a page with all the list options.
GET/v1/social/posts/{id}/reply_toThe post this record points at.

Try it

List with a filter
curl "https://api.sondahub.com/v1/social/posts?visibility=followers&expand=author&limit=3"
One record
curl https://api.sondahub.com/v1/social/posts/1?expand=author
Its comments
curl "https://api.sondahub.com/v1/social/posts/1/comments?limit=5"
Create
curl -i -X POST https://api.sondahub.com/v1/social/posts \
  -H "Content-Type: application/json" \
  -d '{"author_id":1,"body":"A body","visibility":"public","language":"en"}'
Read it back: newest first (send the session token)
curl "https://api.sondahub.com/v1/social/posts?sort=-id&limit=3" \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"
Change one field
curl -X PATCH https://api.sondahub.com/v1/social/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"visibility":"followers"}'
Delete the one you created
curl -X DELETE https://api.sondahub.com/v1/social/posts/4001 \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"

comments

Comments on posts; a comment can answer another comment through parent_id. 8,000 records — the file, or the comments API page with sample records.

POST bumps the post’s comments_count; DELETE lowers it.
FieldTypeNotes
idread-onlyintAssigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.
created_atread-onlydatetimeWhen the record was created (ISO 8601, UTC).
updated_atread-onlydatetimeWhen the record last changed.
post_idrequiredint → posts
author_idrequiredint → users
parent_idint → comments
bodyrequiredtext
likes_countread-onlyint
flaggedbool

Relations: post → one post through post_id; author → one user through author_id; parent → one comment through parent_id; replies → the comments whose parent_id is this comment. Use ?expand=post,author,parent,replies to embed them, or the nested routes.

Endpoints

GET/v1/social/commentsA page, with every filter, sort, search, field and expand option.
POST/v1/social/commentsCreate one: 201 with the record, its id, a Location header and the session token that keeps it; 422 names each field that is wrong.
GET/v1/social/comments/{id}One record, with an ETag; If-None-Match earns a 304.
PATCH/v1/social/comments/{id}Change the fields you send.
PUT/v1/social/comments/{id}Replace the record; required fields must all be there.
DELETE/v1/social/comments/{id}Answers 200 with what was removed (a real server’s 204 lives at /v1/utils/status/204); gone for the session.
GET/v1/social/comments/{id}/postThe post this record points at.
GET/v1/social/comments/{id}/authorThe user this record points at.
GET/v1/social/comments/{id}/parentThe comment this record points at.
GET/v1/social/comments/{id}/repliesIts comments, as a page with all the list options.

Try it

List with a filter
curl "https://api.sondahub.com/v1/social/comments?expand=post&limit=3"
One record
curl https://api.sondahub.com/v1/social/comments/1?expand=post
Its replies
curl "https://api.sondahub.com/v1/social/comments/1/replies?limit=5"
Create
curl -i -X POST https://api.sondahub.com/v1/social/comments \
  -H "Content-Type: application/json" \
  -d '{"post_id":1,"author_id":1,"body":"A body"}'
Read it back: newest first (send the session token)
curl "https://api.sondahub.com/v1/social/comments?sort=-id&limit=3" \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"
Change one field
curl -X PATCH https://api.sondahub.com/v1/social/comments/1 \
  -H "Content-Type: application/json" \
  -d '{"body":"Changed body"}'
Delete the one you created
curl -X DELETE https://api.sondahub.com/v1/social/comments/8001 \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"

likes

A user liking a post. POST one to like; DELETE it to unlike. 8,000 records — the file, or the likes API page with sample records.

POST refuses a second like of the same post by the same user (409 already_liked) and bumps the post’s likes_count; DELETE lowers it.
FieldTypeNotes
idread-onlyintAssigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.
created_atread-onlydatetimeWhen the record was created (ISO 8601, UTC).
updated_atread-onlydatetimeWhen the record last changed.
user_idrequiredint → users
post_idrequiredint → posts

Relations: user → one user through user_id; post → one post through post_id. Use ?expand=user,post to embed them, or the nested routes.

Endpoints

GET/v1/social/likesA page, with every filter, sort, search, field and expand option.
POST/v1/social/likesCreate one: 201 with the record, its id, a Location header and the session token that keeps it; 422 names each field that is wrong.
GET/v1/social/likes/{id}One record, with an ETag; If-None-Match earns a 304.
PATCH/v1/social/likes/{id}Change the fields you send.
PUT/v1/social/likes/{id}Replace the record; required fields must all be there.
DELETE/v1/social/likes/{id}Answers 200 with what was removed (a real server’s 204 lives at /v1/utils/status/204); gone for the session.
GET/v1/social/likes/{id}/userThe user this record points at.
GET/v1/social/likes/{id}/postThe post this record points at.

Try it

List with a filter
curl "https://api.sondahub.com/v1/social/likes?expand=user&limit=3"
One record
curl https://api.sondahub.com/v1/social/likes/1?expand=user
Create
curl -i -X POST https://api.sondahub.com/v1/social/likes \
  -H "Content-Type: application/json" \
  -d '{"user_id":1,"post_id":1}'
Read it back: newest first (send the session token)
curl "https://api.sondahub.com/v1/social/likes?sort=-id&limit=3" \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"
Change one field
curl -X PATCH https://api.sondahub.com/v1/social/likes/1 \
  -H "Content-Type: application/json" \
  -d '{}'
Delete the one you created
curl -X DELETE https://api.sondahub.com/v1/social/likes/8001 \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"

follows

follower_id follows followee_id. 5,000 records — the file, or the follows API page with sample records.

POST refuses following yourself and duplicates (409); following a private user starts pending; active follows move both users’ counters.
FieldTypeNotes
idread-onlyintAssigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.
created_atread-onlydatetimeWhen the record was created (ISO 8601, UTC).
updated_atread-onlydatetimeWhen the record last changed.
follower_idrequiredint → users
followee_idrequiredint → users
statusenumactive pending blocked
notificationsbool

Relations: follower → one user through follower_id; followee → one user through followee_id. Use ?expand=follower,followee to embed them, or the nested routes.

Endpoints

GET/v1/social/followsA page, with every filter, sort, search, field and expand option.
POST/v1/social/followsCreate one: 201 with the record, its id, a Location header and the session token that keeps it; 422 names each field that is wrong.
GET/v1/social/follows/{id}One record, with an ETag; If-None-Match earns a 304.
PATCH/v1/social/follows/{id}Change the fields you send.
PUT/v1/social/follows/{id}Replace the record; required fields must all be there.
DELETE/v1/social/follows/{id}Answers 200 with what was removed (a real server’s 204 lives at /v1/utils/status/204); gone for the session.
GET/v1/social/follows/{id}/followerThe user this record points at.
GET/v1/social/follows/{id}/followeeThe user this record points at.

Try it

List with a filter
curl "https://api.sondahub.com/v1/social/follows?status=pending&expand=follower&limit=3"
One record
curl https://api.sondahub.com/v1/social/follows/1?expand=follower
Create
curl -i -X POST https://api.sondahub.com/v1/social/follows \
  -H "Content-Type: application/json" \
  -d '{"follower_id":1,"followee_id":2,"status":"active"}'
Read it back: newest first (send the session token)
curl "https://api.sondahub.com/v1/social/follows?sort=-id&limit=3" \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"
Change one field
curl -X PATCH https://api.sondahub.com/v1/social/follows/1 \
  -H "Content-Type: application/json" \
  -d '{"status":"pending"}'
Delete the one you created
curl -X DELETE https://api.sondahub.com/v1/social/follows/5001 \
  -H "X-Sondahub-Session: THE_TOKEN_FROM_THE_CREATE"

WebSocket and SSE

The same stream two ways: the world's own activity, one tick a second, generated for your connection alone. Both push JSON text messages; SSE names each one with event: and numbers it with id:. ?topics=a,b narrows either.

TopicWhat arrivesHow often
postsA new post from one of the seed users.5 s
likesSomeone liking something.2 s
WebSocket
wss://api.sondahub.com/v1/social/ws?topics=posts

> {"type":"hello","api":"social","topics":[…],"subscribed":[…]}
> {"type":"event","topic":"posts","api":"social","ts":"…","data":{…}}
< {"type":"subscribe","topics":["posts"]}   # narrow to some topics
< {"type":"ping"}                            # → {"type":"pong"}
< anything else                             # → echoed back as {"type":"echo"}
Server-Sent Events
curl -N "https://api.sondahub.com/v1/social/events?topics=posts"

retry: 3000
id: 1
event: posts
data: {"type":"event","topic":"posts",…}

Socket.IO

The namespace /social on the Socket.IO server at https://api.sondahub.com (path /socket.io/, WebSocket transport): every call over an acknowledgement — getUser, listUsers and the rest — answered { ok, data } or { ok, error }, and the topics above pushed as events of the same names. Writes keep for the connection, and a session event carries them to the next one. More on the Socket.IO server.

socket.io-client
const s = io('https://api.sondahub.com/social', { transports: ['websocket'] })
s.on('posts', (e) => console.log(e))
const { data } = await s.emitWithAck('getUser', { id: 1 })

GraphQL

One endpoint, https://api.sondahub.com/v1/social/graphql: POST {"query", "variables"} or GET ?query=. Introspection is on, so Sonda's GraphQL mode loads the schema; the SDL is a click away. Every collection is a paged query with the same filter, sort and q options as REST (operators as suffixes: price_lt), a by-id query, relation fields both ways, and create, update, replace and delete mutations — simulated like every write, with the note in extensions.

A query
curl https://api.sondahub.com/v1/social/graphql -H "Content-Type: application/json" -d '{"query": "{ posts(limit: 3, sort: \"-id\", filter: { visibility: public }) { total data { id author_id body visibility author { username } comments(limit: 2) { id } } } }"}'
{
  posts(limit: 3, sort: "-id", filter: { visibility: public }) {
    total
    data {
      id author_id body visibility
      author { username }
      comments(limit: 2) { id }
    }
  }
}

OData

The API is also an OData 4.0 service at https://api.sondahub.com/odata/social/: its $metadata, an entity set per collection with the relations as navigation properties, the whole $filter language, nested $expand, $count, $search, paging, writes with ETags and $batch. Power BI and Excel read it as an OData feed. More on OData.

users, OData
curl -G https://api.sondahub.com/odata/social/users \
  --data-urlencode "\$top=3" \
  --data-urlencode "\$count=true"

gRPC-Web and Connect

The API is also the protobuf service sondahub.social.v1.SocialService, generated from the same registry as REST, so the wire and the docs cannot disagree. The .proto file is one click away; feed it to protoc, buf or your codegen. Calls go to https://api.sondahub.com/grpc/sondahub.social.v1.SocialService/{Method} over gRPC-Web (binary or text) or Connect (JSON or binary; GET for reads). Writes keep to the session like every other write. More on gRPC-Web.

MethodWhat
ListUsersA page of users: page, limit, sort, q and filter (field → value, with the REST operator suffixes: price_lt → 20).
GetUserOne user by id.
CreateUserCreate a user (simulated, kept in your session token). id and the timestamps are set by the server.
UpdateUserChange the fields set in user (simulated).
DeleteUserDelete one (simulated); answers what was removed.
ListPostsA page of posts: page, limit, sort, q and filter (field → value, with the REST operator suffixes: price_lt → 20).
ListCommentsA page of comments: page, limit, sort, q and filter (field → value, with the REST operator suffixes: price_lt → 20).
ListLikesA page of likes: page, limit, sort, q and filter (field → value, with the REST operator suffixes: price_lt → 20).
ListFollowsA page of follows: page, limit, sort, q and filter (field → value, with the REST operator suffixes: price_lt → 20).
Watch
server stream
The API's live activity as a server stream, each topic at its own pace: posts (every 5 s), likes (every 2 s). max_events ends the stream (default 10, at most 120).

Every collection has List, Get, Create, Update and Delete; the table shows them for users and the lists for the rest.

GetUser, Connect over GET
curl "https://api.sondahub.com/grpc/sondahub.social.v1.SocialService/GetUser?encoding=json&message=%7B%22id%22%3A1%7D"
ListUsers, Connect JSON
curl -X POST https://api.sondahub.com/grpc/sondahub.social.v1.SocialService/ListUsers \
  -H "Content-Type: application/json" \
  -d '{"limit": 3, "sort": "-id"}'

SOAP, JSON-RPC and XML-RPC

The same five calls per collection, the older ways. SOAP: the service described by its WSDL, document/literal over SOAP 1.1 and 1.2, operations like GetUser, and a twin behind WS-Security at https://api.sondahub.com/soap/secure/social. JSON-RPC 2.0 at https://api.sondahub.com/jsonrpc and XML-RPC at https://api.sondahub.com/xmlrpc, methods like social.getUser. Writes keep to the session like every other write. More on SOAP · more on JSON-RPC and XML-RPC.

social.getUser, JSON-RPC
curl https://api.sondahub.com/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "social.getUser", "params": [1]}'
GetUser, SOAP 1.1
curl https://api.sondahub.com/soap/social \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPAction: "https://sondahub.com/soap/social/GetUser"' \
  -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:s="https://sondahub.com/soap/social">
  <soap:Body>
    <s:GetUser><s:id>1</s:id></s:GetUser>
  </soap:Body>
</soap:Envelope>'