Overall format/structure - incorporating best practices from UPI API/Tech Spec doc

[rahul101001000]

The UPI API/Tech spec doc (link) is one of the easiest to understand. See section 2.6 that gives use cases (external and internal view), followed by sequence diagrams and failure scenarios in section 3.1, and the API examples in 3.4. This structure ensures the information provided is comprehensive, logically derived from the previous section, and most importantly anchored in use cases.

Could we use elements of this structure/format for the technical specification for Sunbird-RC. Right now the spec misses out on readability and comprehensiveness. Happy to help in any way. @pramodkvarma

[pramodkvarma]

Sure, do you want to contribute this? You can edit the specs page (your version) and send for review. We can then do a PR to bring it in.

[rahul101001000]

Sure @pramodkvarma, let me start with editing one page - Edu use cases and express use cases in the following format -

1. End user experience flow
2. Behind the scenes flow
3. Sequence diagram with API calls and schema references
4. Pointer to example code

If this is useful then can structure other pages better as well.

[pramodkvarma]

Please do check out existing work by @jayadinni and @kshitij-design and build on top of that

[rahul101001000]

Most definitely. Please do send any pointers. Right now seeing only a skeleton doc on the link I shared.

…

On Fri, 1 Oct 2021, 08:05 Pramod Varma, ***@***.***> wrote: Please do check out existing work by @jayadinni <https://github.com/jayadinni> and @kshitij-design <https://github.com/kshitij-design> and build on top of that — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#65 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/APGX7MIG2WL7IJQ7YWZYIFTUEUNANANCNFSM5E4PJQNQ> .

[jayadinni]

@rahul101001000 Here is high level user flow

[rahul101001000]

This is great, thank you @jayadinni !

I was looking for something like the DEPA sequence diagrams. What I like about this is that the arrows have not only the API call being made but also the schema for the object being passed.

Maybe in the current diagram itself, API endpoint and schema may be added?

Also I'm not finding the API docs or schemas, could you please point to them.

Thanks in advance,

Regards
Rahul