Fix the god-awful api documentation

[BOOP]

It's just inconvenient, I propose using some open source software for API docs (i.e Swagger I think)

 

[Ally]

I think a less blunt and more descriptive way to put it is thus (having just fully implemented a wrapper in C#, myself):

1. During some tests, I found that a few spelling mistakes of query parameters and body keys are present.
2. There is one particular response type, that isn't quite like anything in the documentation objects and that is separate, which could in fact just be integrated into one of the objects.
3. There are mistakes on the server (end e.g. wrapping a Version[] in an undocumented object presumably for testing).
4. Return types are unclear on methods which patch or post, and my current wrapper assumes those are all uints.

The best solution, depending on how the API is implemented, is, if your API is OpenAPI compliant, using Swagger:

1. There is no possibility for misspelling parameters.
2. Any and every object can and is sufficiently documented in one place, and UI testing provides sufficient examples.
3. Swagger UI and similer projects allow for on the fly testing of your API and tell you what you send and return.
4. Swagger UI can also assist in documenting return types.

If the API isn't compliant, perhaps building a wrapper first and then documenting that using a system of some kind. I've just tried out doxygen; it may be worth trying out for you guys, too. You can see this example here.
Updated url.

 

[Harry]

It was decided that we keep all documentation onsite in the form of Wiki pages rather than use any external service. Whether we want to reconsider that now after release, I'm unsure. I did originally want to use GitBooks, but after having written the documentation, I really don't feel that's necessary.

But with that constraint in mind, I do think the documentation is at a decent point at the moment. It's in no way perfect, and Ally points some issues out above that I'll be happy to address.

1. During some tests, I found that a few spelling mistakes of query parameters and body keys are present.
2. There is one particular response type, that isn't quite like anything in the documentation objects and that is separate, which could in fact just be integrated into one of the objects.

Could you be a bit more specific about those?

There are mistakes on the server (end e.g. wrapping a Version[] in an undocumented object presumably for testing).

Looks like a typo of a single character which prevented the usual error checking. I've pushed a fix but will wait to see if any more issues prop up before we push it to prod.

Return types are unclear on methods which patch or post, and my current wrapper assumes those are all uints.

For anything that isn't applicable (eg. response data, sort options, query parameters), that heading is omitted. I could be verbose and use "N/A", but that just feels clunky to me.
So the implication from that should be that PATCH requests don't return data.
POSTs return the ID of the content created. I'm just about to fix two instances within the documentation where the response data header wasn't present for a POST request.

 

[Ally]

Could you be a bit more specific about those?

Yep sorry, just off the top of my head at the moment, recipients_ids is misspelt in the docs and should be recipient_ids. Unfortunately I can't think of any more, and there are still quite a few tests I've yet to do since I don't have any paid resources (if you'd like to help, I'd be stoked lol).
For the latter bit- https://www.mc-market.org/wiki/v1-endpoints/#:~:text=a UNIX timestamp-,Response Data,-Code:
The response type is just a Purchase object with "purchase_name" added. You can update the purchase object with that field and let it be known that "purchase_name" is only returned under special circumstances.

For anything that isn't applicable (eg. response data, sort options, query parameters), that heading is omitted. I could be verbose and use "N/A", but that just feels clunky to me.
So the implication from that should be that PATCH requests don't return data.
POSTs return the ID of the content created. I'm just about to fix two instances within the documentation where the response data header wasn't present for a POST request.

Probably worth mentioning at the top to be honest. (PATCH spec doesn't specifically disallow having response bodies). Cheers

 

[Harry]

Yep sorry, just off the top of my head at the moment, recipients_ids is misspelt in the docs and should be recipient_ids. Unfortunately I can't think of any more, and there are still quite a few tests I've yet to do since I don't have any paid resources (if you'd like to help, I'd be stoked lol).
For the latter bit- https://www.mc-market.org/wiki/v1-endpoints/#:~:text=a UNIX timestamp-,Response Data,-Code:
The response type is just a Purchase object with "purchase_name" added. You can update the purchase object with that field and let it be known that "purchase_name" is only returned under special circumstances.

Fixed those. I'll look through it again when I have time.
To mention quickly, I had modified that endpoint to completely remove the "purchaser_name" field so it was consistent with the License object but clearly forgot to update it for that endpoint.

Probably worth mentioning at the top to be honest. (PATCH spec doesn't specifically disallow having response bodies). Cheers

I don't feel that's necessary since even for PATCH requests though, you're still receiving a response body - the API response itself.
It's just that the "data" field is null, and that's completely at our discretion, not the semantics of the request type.