Simple getting started with API guide

[TopSwagCode]

Hi. Do you guys have some getting started using API guides, for people who just want to play around and explore?

Tried bunch of stuff that didn't work and then tried asking ChatGPT that didn't really help at all :D

Link to chat:

https://chatgpt.com/share/681a54d8-7d40-800b-bfe4-f40e24cb9de1

docker run -ti -p 8080:8080 ghcr.io/xregistry/xrserver-all

I looked at https://github.com/xregistry/spec/blob/main/schema/schemas/openapi.json

Any help getting started would be awesome :)

[duglin]

Hi @TopSwagCode. First, as you've probably noticed the repo is still very much focused on just trying to keep up with the spec and as a result the "user friendliness" is lacking a bit. So I'm glad you pinged us so that we can know where we need to focus our time to help newcomers when we get a chance to come up for air from working on the core features.

With that... let's start at the beginning.... what's the first task you're trying to do? In your chatgpt you mentioned just creating a group, but there are two ways to interpret that so let's me see if this helps:

• when you run the "xrserver-all" image you'll get an empty xRegistry instance.
• if you hit it (e.g. curl localhost:8080), you should see something like this:

{
  "specversion": "1.0-rc1",
  "registryid": "xRegistry",
  "self": "http://localhost:8080/",
  "xid": "/",
  "epoch": 1,
  "createdat": "2025-05-06T18:47:37.084362016Z",
  "modifiedat": "2025-05-06T18:47:37.084362016Z"
}

which is just the top-level metadata about the registry. Notice there isn't anything in there that would lead you think that there are other objects in the system (or even known to the system), like "groups". For example, there's no "groupsurl" type of attribute you can follow to get the list of groups. That's because not only are there no groups yet, but there isn't even the definition of a "group type". In other words, the model is basically empty. We didn't want to assume any particular model so we opted for "none" as of now.

However you could ask for some sample models to be loaded (via the --samples) flag, but let's assume you want to add your own.... meaning your desire to "create a group" was really "create a group TYPE".

Very near the top of our todo list is to make an "xr" CLI command to do that w/o writing JSON, but as of now you'll need to something less than user-friendly like this:

echo '
{
  "groups": {
    "mygroups": {
      "singular": "mygroup"
    }
  }
}
' | xr model update -d @-

You could also use curl if you don't want to download the xr CLI (https://github.com/xregistry/server/releases/tag/dev):

echo '             
{
  "groups": {
    "mygroups": {
      "singular": "mygroup"
    }
  }
}
' | curl -X PUT localhost:8080/model -d @-

That updates the model of this registry instead to have one group type called "mygroups" (the plural name) and "mygroup" as its singular name. Nothing else is created.

Now doing a curl should show the pointers I hinted at via the "mygroups..." attributes:

{
  "specversion": "1.0-rc1",
  "registryid": "xRegistry",
  "self": "http://localhost:8080/",
  "xid": "/",
  "epoch": 1,
  "createdat": "2025-05-06T18:47:37.084362016Z",
  "modifiedat": "2025-05-06T18:47:37.084362016Z",

  "mygroupsurl": "http://localhost:8080/mygroups",
  "mygroupscount": 0
}

Let me stop there to see if that's at least close to what your first step is trying to do. Then we can continue...

and again, thanks for pinging!

[duglin]

Also, if you do run the 'xr' command you can specify -vv to see all of the HTTP commands it runs so you replicate the same logic via curl or programmatically. So, with that model update command, for me, -vv shows (among other things):

2025/05/06 19:01:24 Request: PUT http://ubuntu:8080/model
2025/05/06 19:01:24 Request Body:
{"groups":{"mygroups":{"singular":"mygroup"}}}

[TopSwagCode]

Thank you for the quick response. I will try out the CLI. Is the CLI self documented? Or is there some place I can read more about it? Or should I just read the source code for it ? :)

[TopSwagCode]

After spending some minutes. Can you point me in the direction where I can read about doing some basic stuff eg:

Create 2 different groups. Each with 5 endpoints + schemas. Don't really care about user friendlyness. As long as I just know the json models to work with the CLI.

[duglin]

@TopSwagCode sorry for the delay - got busy with something, but wanted to write back before I finished for the day.

Try a few things:

• See https://github.com/xregistry/server/blob/master/samples/doc-store This shows how to use the new "xr model ... " commands to create Group and Resource types for the model. Then it'll just create some instance data based on that model.
• Then see: https://github.com/xregistry/server/blob/master/samples/endpoints That's closer to what you're looking for. That will upload the CloudEvent model (which has endpoints, message groups and schema groups as part of the model). It will then populate it with instance data for a fake company called Contoso.

See if that helps.