Skip to content

Commit babd4e6

Browse files
AnanthaRajuCAnanthaRajuC
committed
docs: UPDATED
1 parent b07a808 commit babd4e6

File tree

3 files changed

+74
-10
lines changed

3 files changed

+74
-10
lines changed

‎documents/API.md‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,53 @@
11
## API
22

3+
This application comes with an out-of-the-box API, which will allow you to provide an API to your users or build a mobile app from your API.
4+
5+
### Access Data from the API
6+
7+
In order to access data from the API a user or an application will need to pass an Access Token to the API. This access token along with the **ROLE** of the user will determine what kind of data can be accessed or returned.
8+
9+
- You can request an Access Token with a **username** and a **password**
10+
11+
To get an Access Token from a User Login you can do a POST request to:
12+
13+
| URL | Method | Remarks | Sample Valid Request Body |
14+
|---------------------------------------------------------------------|--------|-----------------------------------------------|---------------------------|
15+
|`http://localhost:8080/api/v1/auth/login` | POST |Bearer Token, Refresh Token is generated | [JSON](#login) |
16+
17+
You will get a response similar to the one show below.
18+
19+
~~~json
20+
{
21+
"authenticationToken": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIiwiZXhwIjoxNjIxMTYwOTk4fQ.TGDRUuBP25SE4bJU2jTpbNku2ZTqDF-cP0JEI0QdMEslvfH7e9J3cxy4aGe86hqTMCcgED7CwyGHDPqsSVQfCDIJPnhkTdrguZc-4m01blg3-SedCDIDg2Xq6oIsYIIDyY92ITiLKxTclzyj289DokwOfxwSQyrNxIkdCJZ8VoKZUeDjmalXM8uDpS7Cf7-dCgCYi7lFpZH0vma6qq62KNfuRV1zhWh9OT4jRoeaNMvbxn2kRA912yDQ0Y1M4EZFqAtS4m_6hiNw9MJ6KbfgpZ5y2oNlabtCOSlSeHtKyFhnFe0S5CX3Vl03hiALGOpxQPP2ayyy9samCG4qC8l11w",
22+
"refreshToken": "3d0ca7a8-04c5-4bb2-8fe4-0e26b06c6ef1",
23+
"expiresAt": "2021-05-16T10:24:59.722Z",
24+
"username": "johndoe"
25+
}
26+
~~~
27+
28+
You'll see that this response includes additional fields **refreshToken** and **expiresAt**. When your application detects the **authenticationToken** has expired it will need you to request a new **authenticationToken** with the following API request:
29+
30+
| URL | Method | Remarks | Sample Valid Request Body |
31+
|---------------------------------------------------------------------|--------|-----------------------------------------------|---------------------------|
32+
|`http://localhost:8080/api/v1/auth/refresh/token` | POST |Refresh Token from login should be passed | [JSON](#refresh-token) |
33+
34+
35+
##### sample refresh token request body
36+
37+
```json
38+
{
39+
"token":"1178cd43-21d2-45b4-8b5f-c79aa1d5b76e",
40+
"username":"johndoe"
41+
}
42+
```
43+
44+
And you will recieve a new **authenticationToken** for your application to be used. This expiration and refresh tokens are common for keeping your API secure.
45+
46+
### Request Data with an Access Token
47+
48+
Now, that you have an **authenticationToken** you can request data from the application using that token. Based on the permission of the current user they will be able to CREATE, READ, UPDATE, and DELETE content in your application.
49+
50+
351
### API Rate Limiting
452

553
| Tier | API Request Cap | API Key Prefix |
@@ -24,7 +72,6 @@ If the application remains inactive for a specified period of time, the session
2472

2573
This value **server.servlet.session.timeout** can be configured in **application.properties** file
2674

27-
2875
## Explore Rest APIs
2976

3077
The app defines following CRUD APIs. **If localhost doesn't work, use 192.168.99.102**
@@ -35,6 +82,11 @@ Since the SSL certificate is self signed, turn off the **SSL certificate verific
3582

3683
<img src="images\tools\postman-ssl-certificate-verification.PNG"/>
3784

85+
### Authentication, Person, Person Management URLs
86+
87+
- [Authentication API's](/AUTHENTICATION.MD)
88+
- [Person and Person Management API's](/USER_ROLES.MD)
89+
3890
### URLs
3991

4092
| URL | Method | Remarks |
@@ -67,3 +119,4 @@ To monitor and manage your application
67119
|`http://localhost:8080/actuator/info` | GET |
68120
|`http://localhost:8080/actuator/prometheus`| GET |
69121
|`http://localhost:8080/actuator/httptrace` | GET |
122+

‎documents/AUTHENTICATION.MD‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,11 +38,14 @@ The simplest way to test emails in development mode is to use Mailtrap. You can
3838

3939
If you have just installed Spring Boot Application Template you can login with the following default accounts.
4040

41-
| Username | Password |
42-
|------------------|----------|
43-
|`johndoe` |`password`|
44-
|`AdminUser` |`password`|
45-
|`AdminTraineeUser`|`password`|
41+
| Username | Password | Role |
42+
|------------------|----------|--------------|
43+
|`johndoe` |`password`|`PERSON` |
44+
|`janedoe` |`password`|`PERSON` |
45+
|`Admin1` |`password`|`ADMIN` |
46+
|`Admin2` |`password`|`ADMIN` |
47+
|`AdminTrainee1` |`password`|`ADMINTRAINEE`|
48+
|`AdminTrainee1` |`password`|`ADMINTRAINEE`|
4649

4750
| URL | Method | Remarks | Sample Valid Request Body |
4851
|---------------------------------------------------------------------|--------|-----------------------------------------------|---------------------------|

‎documents/USER_ROLES.MD‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,15 @@ Each user in the app will have a primary role and every role has permissions to
55
| Username | Password | Role | Permission | Resource |
66
|------------------|----------|--------------|-------------------------------------------------------|---------------------------|
77
|`johndoe` |`password`|`PERSON` | |`/api/v1/person` |
8-
|`AdminUser` |`password`|`ADMIN` |`PERSON_CREATE,PERSON_READ,PERSON_UPDATE,PERSON_DELETE`|`/management/api/v1/person`|
9-
|`AdminTraineeUser`|`password`|`ADMINTRAINEE`|`PERSON_READ` |`/management/api/v1/person`|
8+
|`janedoe` |`password`|`PERSON` | |`/api/v1/person` |
9+
|`Admin1` |`password`|`ADMIN` |`PERSON_CREATE,PERSON_READ,PERSON_UPDATE,PERSON_DELETE`|`/management/api/v1/person`|
10+
|`Admin2` |`password`|`ADMIN` |`PERSON_CREATE,PERSON_READ,PERSON_UPDATE,PERSON_DELETE`|`/management/api/v1/person`|
11+
|`AdminTrainee1` |`password`|`ADMINTRAINEE`|`PERSON_READ` |`/management/api/v1/person`|
12+
|`AdminTrainee2` |`password`|`ADMINTRAINEE`|`PERSON_READ` |`/management/api/v1/person`|
1013

1114
### Person URLs
1215

13-
#### Accessible to **johndoe** user only
16+
#### Accessible to user's with **PERSON** role only
1417

1518
| URL | Method | Remarks | Sample Valid Request Body |
1619
|----------------------------------------------------------|---------|-------------------------------------------------------------------------------------|---------------------------|
@@ -23,7 +26,7 @@ Each user in the app will have a primary role and every role has permissions to
2326

2427
### Person Management URLs
2528

26-
#### Role and Permission based secure access to **AdminUser** and **AdminTrainee** users
29+
#### Role and Permission based secure access to user's with **ADMIN** role.
2730

2831
| URL | Method | Remarks | Sample Valid Request Body |
2932
|----------------------------------------------------------|---------|-------------------------------------------------------------------------------------|---------------------------|
@@ -34,6 +37,11 @@ Each user in the app will have a primary role and every role has permissions to
3437
|`http://localhost:8080/management/api/v1/person/{id}` | PUT | Update a person | [JSON](#personcreate) |
3538
|`http://localhost:8080/management/api/v1/person/{id}` | DELETE | Delete a person | |
3639

40+
#### Role and Permission based secure access to user's with **ADMINTRAINEE** role.
41+
42+
| URL | Method | Remarks | Sample Valid Request Body |
43+
|----------------------------------------------------------|---------|-------------------------------------------------------------------------------------|---------------------------|
44+
|`http://localhost:8080/management/api/v1/person` | GET | Header `Accept:application/json` or `Accept:application/xml` for content negotiation| |
3745

3846
#### Sample Valid JSON Request Bodys
3947

0 commit comments

Comments
 (0)