# 0x1 Certificate API Doc

- **Github**: https://github.com/yhuag/chain-certificate
- **Endpoint**: https://x1certificate-aqkcbxdduq-uc.a.run.app/ipfs

## Current

| Function | API | Required Field |
| -------- | -------- | -------- |
| View all certificates |`/ipfs` | x |
| Issue new certificates | `/issue?certName=iota&name=tina` | certName, name |

## Goal

| Function | Method | URI | Required Fields | Returns | Access Right |
|:------------------------------------------:|:------:|:--------------------------------------:|:--------------------------------:|:---------------------:|:-------------------:|
| **View Certificates** | | | | | |
| View all certs | GET | `/certs` | x | A list of certs | Anyone |
| View all certs holders | GET | `/certs/holders` | x | A list of certs holders | Anyone |
| View all certs types | GET | `/certs/types` | x | A list of certs types | Anyone |
| View all certs of a specified holder | GET | `/certs?holder=tina` | holder | A list of certs | Anyone |
| View all certs of a specified type | GET | `/certs?type=hkust` | type | A list of certs | Anyone |
| **Manage Issuer** | | | | | |
| Register as an issuer of a specified type | POST | `/issuers?type=hkust` | type | issuer ID | Admin |
| Revoke an issuer for a specified type | DEL | `/issuers?type=hkust` | type | issuer ID | Admin |
| **Issue Certificates** | | | | | |
| Issue a certificate of a type | POST | `/issue?type=hkust` | type | x | Issuer of that type |
| Issue a batch of certificates of a type | POST | `/issue?type=hkust` | type; request body with an array | x | Issuer of that type |
| **Revoke Certificates** | | | | | |
| Revoke a certificate of a type | DEL | `/certs?type=hkust` | type | x | Issuer of that type |
| Revoke a batch of certificates of a type | DEL | `/certs?type=hkust` | type; request body with an array | x | Issuer of that type |
| **Verify Certificates** | | | | | |
| Verify a certificate of a specified holder | GET | `/certs/verify?holder=tina&type=hkust` | holder; type | A boolean value | Anyone |

## Goal (Old)

| Function | API | Required Field |
| -------- | -------- | -------- |
| **View** | | |
| All certs (Temporarily Available) |`/view` | x |
| All cert types |`/view/type` | x |
| Specific cert type |`/view?certName=iota` | x |
| Specific owner |`/view?owner=tina` | x |
| **Issue** | | |
| One cert | `/issue/new?certName=iota&owner=tina` | certName, owner |
| Batch certs | `/issue/new?certName=iota&owners=xxx.csv` | certName, owners |
| Revoke | `/issue/revoke?certName=iota&owner=tina` | certName, owner |
| **Verify** | | |
| Specific cert | `/verify?certName=iota&owner=tina` | certName, owner |
| **Admin** | | |
| Assign new issuer; return new issuer access token | `/admin/newIssuer?certName=iota` | certName |
| Revoke issuer | `/admin/revokeIssuer?certName=iota` | certName |

## TODO
- [x] Reorganize code
- Modularize all index_xxx.js files
- Make them all similar to index_iota.js
- [ ] Require credentials for Admin and Issuer
- We, as Admin, have the admin secret key
- We will give the Issuer a access token
- Only Issuer for specific cert type can issue and revoke certs
- [ ] Define standard schema for cert, issuer, and owner (reference W3C DID)
- cert schema
- ID (ipfs hash)
- owner
- certName
- issuer
- timestamp
- isValid (revoked or not)
- [ ] Track all certs by ID
- create a table that maps cert ID to cert owner, cert name, etc, according to cert schema
- can view, verify, revoke cert by ID
- [ ] Store all cert schema data in our DB, for emergencies
- [ ] Speed up ipfs loading speed
- https://github.com/ConsenSys/Mahuta
- [ ] Integrate with IOTA TangleID
- https://github.com/TangleID/TangleID

## References
- [Rest API Best Practices](https://restfulapi.net/resource-naming/)
- [HTTP Status Code Cheatsheet](https://codeburst.io/know-your-http-status-a-cheat-sheet-for-http-status-codes-5fb43863e589)