Initial meeting doc #74
Conversation
| ### Meeting Query | ||
|
|
||
|
|
||
| ```graphql |
There was a problem hiding this comment.
The other guides use a tabular format. Most guides cover the documentation of a single type in the schema, though in the case of the moments doc, we used section headers per type with a table within each. The new fields on existing types, like the meeting field on QueryRoot, might be best demonstrated in a subset in the nav with an example?
There was a problem hiding this comment.
I followed the example of Reactions (like guides/V1_Reacting_Users.md) because I think it was what Miguel pointed me to. The Reactions doc used GraphQL type definition language instead of tables. I'm fine either way, but will hold off on changes unless you strongly disagree.
There was a problem hiding this comment.
OK - I think that reactions guide isn't published into the nav yet @miguelestrada and most of the guides already in the nav use a more tabular format?
If we want something in this GraphQL type format - I think we should just generate it in the GraphQL server itself. This is also not too different from what you actually already see in the sidebar of the GraphQL explorer, so not sure there is huge value in copying this here into a doc we need to update separately? I think the doc gives us the opportunity to say more about each field we add, and I'm not sure the graphql type language really allows us to do that.
I'm 100% for using these type definitions in our internal designs and specs, but I don't know if redundantly adding these into the doc when you can find something similar in the GraphQL explorer, is helpful.
One other thing we could explore in the future though - we could try to make the GraphQL explorer tool responsive to URLs that could open the doc sidebar to a specific type. Then we could make the type names clickable links perhaps and avoid redefining things here.
| ## Example Request | ||
|
|
||
| ~~~~ | ||
| Method: POST |
There was a problem hiding this comment.
In the other guides we use a link to the GraphQL tool to show queries like this - so you can just copy/paste the query into the tool, then grab the URL from the tool. You will need apiType=experimental on the URL for this one. I was recently doing the moments doc in a similar way if you want to check it out.
guides/V1_Meeting.md
Outdated
| Body: | ||
| { | ||
| query { | ||
| meeting(spaceId: "5a9ee86ee4b0cb1ca3dfef33") { |
There was a problem hiding this comment.
There is a convention used in the docs for using "space-id" as a placeholder ID I think. I think the use of the variables section might be better if we explained it up front and did it consistently, but even then I think we'd need a placeholder space ID to serve as an example. I think it's better to use an obvious placeholder like space-id rather than a real ID.
|
|
||
| ## Concepts | ||
|
|
||
| The _startMeeting_ mutation allows the API caller to start a meeting with a **space**. The mutation accepts a Space ID (spaceId) as an argument, and makes the request on behalf of the caller, starting a meeting within the specified space. The result will reflect the whether the call was accepted for processing by the service. |
There was a problem hiding this comment.
can the JWT used on this API call be that of an appID as identity and as client or does it expect a person as the identity?
There was a problem hiding this comment.
Good question. The back-end implementation doesn't care provided the identity represented by the JWT token has the proper permission: meeting_host I don't know if an app can be assigned that permission, or if there are gaps around that.
|
bump on this one @chris-price-772 @brunnjf (it already got conflict on the what's new....) |
|
@chris-price-772 bump on this again.... I already shared with someone the actual .md files btw.... |
|
@brunnjf : Do you think this is read to go? I resolved conflicts and added details about things which had changed since the last review. |
No description provided.