Fix reference json payload file

[berkes]

Description of change

Added a required field. Removed a field that caused the serde to panic.

Links to any relevant issues

No known issue.

How the change has been tested

Manually using curl and httpie.

Definition of Done checklist

Add an x to the boxes that are relevant to your changes.

• I have followed the contribution guidelines for this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have successfully tested this change in a docker environment

[daniel-mader]

• The file seems to be unused, but we could refer to it in the openapi.yaml.
• The filename open-badge-request.json suggests an Open Badge 3.0 payload, where the proposed change indicates a W3C VC Credential.

[berkes]

I used the file to debug with https://httpie.io/ (http client). But dropping it entirely is fine with me too. I used it as documentation.

I prefer httpie for its simplicity, it's not a bloated GUI app (postman) and rather ergonomic compared to curl. I guess the file could be used with curl too, though. Having reference payloads anywhere is IMO very good documentation: much better than poring through a 400+ line postman_collection.json. But maybe that's just me :)

In any case: having documentation that's outdated because its unused is probably worse than not having it at all.

So, fine with me to close this PR and remove the stale "documentation".

[berkes]

The filename open-badge-request.json suggests an Open Badge 3.0 payload, where the proposed change indicates a W3C VC Credential.

That was exactly what I was trying to debug and research. Somehow (my configuration of) the SSI-agent panicked on the OB so I was looking at how the payload should be shaped.

[daniel-mader]

I prefer httpie for its simplicity, it's not a bloated GUI app (postman) and rather ergonomic compared to curl. I guess the file could be used with curl too, though. Having reference payloads anywhere is IMO very good documentation: much better than poring through a 400+ line postman_collection.json. But maybe that's just me :)

I agree that we should consider adding something simpler for "quick try out"/developers/external contributors (such as httpie).
We use Postman mainly for "internal testing" and we make use of its scripting capabilites to set some values and payloads in a flow automatically, so we can quick click through entire flows without having to manually edit each request all the time.

Our main goal is to provide technical API documentation through an OpenAPI file (can be found in agent_api_rest/openapi.yaml) which will also contain request and response examples. You can load that file into your favorite editor (such as Swagger) and explore the API yourself.

We will try to find a nice way to generate httpie examples that use the same payloads as in the OpenAPI file.

In any case: having documentation that's outdated because its unused is probably worse than not having it at all.

Yes, you're absolutely right. 👍 I share the same opinion and this shouldn't have happened. We'll investigate how we could best detect such inconsistencies (preferably automated).

So, fine with me to close this PR and remove the stale "documentation".

We can leave it open until the upcoming "Documentation refactoring" PR is done and then decide.

Thank you for the great feedback! It's much appreciated 👍

[daniel-mader]

Closing due to inactivity. API documentation will be auto-generated in #116.