Technical Analysis - Discuss idagram and docs

[MoeNick]

No description provided.

[mohammadranjbarz]

@MoeNick @aminlatifi @CarlosQ96
This has come to my mind about entity relationship

Flow ( if we approve this scenario, each item could be at least on task)

• Admins can create an application for an existing organization (from admin panel)
• We would have some scopes in our DB, for instance project:create, donation:create, user:update, logs:view
• Admins can specify each application has what scopes (from admin panel)
• Third parties can call an endpoint and get an access token for their applications ( the accessTokens can have application's scopes, from one to all)
• Third parties can use their accessToken to call our APIs
• Third parties can revoke their accessToken by another webservice
• Admins can revoke AccessTokens from admin panel
• If application have IP ( array) , we just allow third parties to call our webservice from that IP
• For each request that comes from third parties we should create a record in log table
• We must generate a trackId and save in log record
• Third parties should be able to get logs by pagination or get one log by trackId
• Admins can view the logs in admin panel

[CarlosQ96]

We should add on top a rate limit.

[CarlosQ96]

We should add versioning on top. Since now other companies will use our API, if we add big version changes we might break their app.

[CarlosQ96]

I am concerned with the registration flow. I think we should:

1. Have a form organizations can fill with their emails and description, mision and why they want to use our api.
2. This would create a record in a table where an admin can approve or contact further the organization with their provided email. (set scopes, etc)
3. If everything is alright, we proceed to create a clientId and send back to the organization email the info encrypted. With their available scopes and api docs. (the givingblocks does something cool like this sending all encrypted).
4. Like you wrote, third parties would request an access token with the scopes they want to use. This would generate one with an expiration. (Must be a POST request, no GET because GET requests cache params)
5. We would do a refresh endpoint. This checks if the token is not revoked.

I think everything else you listed is good! Logs is a really good idea that must be implemented early so we avoid pain points later.

My last questions would be:
Should tokens be infinitely refreshable? should we set a second expiration where they have to request a new one after say 30 days? Should they send the clientId again for refreshing or maybe the email that is less sensitive?

Let me what you think!

[mohammadranjbarz]

I am concerned with the registration flow. I think we should:

1. Have a form organizations can fill with their emails and description, mision and why they want to use our api.
2. This would create a record in a table where an admin can approve or contact further the organization with their provided email. (set scopes, etc)
3. If everything is alright, we proceed to create a clientId and send back to the organization email the info encrypted. With their available scopes and api docs. (the givingblocks does something cool like this sending all encrypted).
4. Like you wrote, third parties would request an access token with the scopes they want to use. This would generate one with an expiration. (Must be a POST request, no GET because GET requests cache params)
5. We would do a refresh endpoint. This checks if the token is not revoked.

I think everything else you listed is good! Logs is a really good idea that must be implemented early so we avoid pain points later.

My last questions would be: Should tokens be infinitely refreshable? should we set a second expiration where they have to request a new one after say 30 days? Should they send the clientId again for refreshing?

Thanks for sharing your ideas,
I agree with what you said, but just one thing currently we don't send emails directly from our backend ( All emails go through auto pilot), so we need to
Use an email service in our backend

About expiration, these two approaches came to my mind

1. Organization request to our server (with their apiKey) and we generate (accessToken + refreshToken) for them, usually accessToken has very short lifeTime something like 2 hours, and ‍‍ refreshToken has longer lifeTime something like 30 days, so when their accessToken got expired they call webService to get new tokens ( this time with their refreshToken NOT their apiKey) , and get new accessTokens

2. They can just call with their apiKey and get accessToken with limited lifeTime, if it got expired they can get new one

PS Obviously the second one is simpler to implement

Just Kidding

[CarlosQ96]

Hahaha nice one. We kinda know the right answer always but mentally and actively avoid it for simpler implementation 🤣

[MoeNick]

Let's do it Guys :)

[MoeNick]

Any update on this @mohammadranjbarz @CarlosQ96 ?

[mohammadranjbarz]

@MoeNick
https://github.com/Giveth/apiGive/blob/main/diagrams/main_flow.md

This is the last updated diagram that is synced with what I implemented

[MoeNick]

@CarlosQ96 I need your confirmation to move it to done.

[CarlosQ96]

@MoeNick we can move it to done. Mohammad has done a great job.

[MoeNick]

@Cotabe just for you information for APIGIV docs

[Cotabe]

Thanks!!! amazing work guys!!!