README.md

# OMS API 小微企业跨组织人才管理系统 - API开发文档作者：安泓郡 Written by Coder.AN ## Introduction ***OMS:Organization Management System.*** This project was developed by Thinker Group for paticipating in the compatition named *China Students Service Outsourcing Innovation and Entrepreneurship Competition, 2021*. Its purpose is to create a management system to provide convenient services between employers and employees. ***This document is written for front-end developers.*** To be more exact, this part is written for ***Jianhao Sun*** and ***Ningning Liu***. Yes, I hope you can easily understand this document in English. Because most of the *state-of-the-art* documents of technology that you will meet in the future are all in English，it's better for you to adapt it from now on. **Actually, I wrote the document in such sick way is to ensure that you will read every word carefully and will not lost any programming detail or you can't understand the document, haha**. If you really don't understand what the document is saying, please visit the URL ***https://fanyi.baidu.com/*** or ***https://translate.google.com/***. It will help you, **I mean it**! ## How to read this document This document will tell you how many APIs you can call and how to call these APIs. The following is the structure of the document directory. ```bash . +---API | +---admin | | +---API_file_of_admin | | +---... | +---user | | +---API_file_of_user | | +---... | +---hr | | +---API_file_of_hr | | +---... | +---getBaseInfo | +---login +---README.md ``` As you can see, our document contains a three-level structure. In the first level, there is a folder *API* and a file *README.md*. All APIs' instruction is in the folder *API*, and the most important instruction is written in file *README.md* which you are reading currently. In the folder *API*, you can see three folders and two files *getBaseInfo* and *login*. In our OMS, we divide users into three groups: personal users, hr users and administrators. They correspond to ***user***, ***hr***, ***admin***（We name it ***user-type***). Certain user-types can only call APIs in the corresponding folder, except two files named *getBaseInfo* and *login*. Because these two files are public. Besides, there are files named README.md in each sub-folders possibly. Please read them as carefully as possible and you will get some useful information. ## Authority management Although there are many administrators, not each administrator have the authority to register users, delete users, etc. So we must have a method to manage authority. If you choose the identity *administrator* to login the OMS, open the page 'API管理-管理员', you will find that each API have a entry-code(API权限码). If you look closely, you will find that they are all 2<sup>k</sup>. We use **Binary-bit Operation** to mange API-authoriy. Let's see an example. ### Example Here we define that the function *register users* corresponding to entry-code 1, the function *delete users* corresponding to entry-code 2 and the function *get base information* corresponding to entry-code 4. Let's see these three numbers in binary form(use 4-bit binary number as example). ```bash 1:0001 2:0010 4:0100 ``` Also, each administrator has its own entry-code. For example, there is a admin named lichunyu, his entry-code equals 1. And then what will happend? You may know a logical operation called *'and'*（逻辑与&). Please calculate 1&1, what is the result? ```bash 0001 & 0001 ------ 0001 ``` The result equals 1. Then we can think that lichunyu has the authoriy *register users*. And how about calculate 2&1? ```bash 0001 & 0010 ------- 0000 ``` The result is 0. Then we know that lichunyu doesn't have the authority *delete users*. Similarly, he doesn't have the authoriy *get base information*. Assume that lichunyu's entry-code is 3, what will happened? ```bash 0001 & 0011 ------- 0001 0010 & 0011 ------- 0010 ``` As you see, 1&3=1, 2&3=2.Then we can say that lichuyu has the autorities *register users* and *delete users* at the same time. But he doesn't have the authoriy *get base information*. ## How to call these APIs ### Abstract When you send a message to our API server, we say you have made a ***request***. And if nothing unexpected, then the server will give you some infomation you need, we say it have returned you a ***response***. Then I will tell you how to make a request and get the response. ### Request Please send a https request to *https://api.thinker2021.cn* by ***POST*** method. If you feel unfamiliar when you see the words *https* or *POST*, please learn some knowledge about *http*, *SSL*, *GET and POST method*. Try to find is there any framework about https communication in your programming language currently to acheive the function. The content of the POST request must be in this format: ````json data={ "_username":"zhangsan", "_token":"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF", "_usertype":"user", "_request":"getBaseInfo", "key1":"value1", "key2":"value2", "key3":"value3" } ```` * **_username** You must tell the API server ***WHO*** is asking for information now. This is the name of the user. * **_token** All legal user will get a secret key when he/she login the system, which is called ***TOKEN***. It is a 32-bit hexadecimal string. * **_usertype** We divide the users into three groups: personal users, HR users and administrators. They correspond to ***user***, ***hr*** and ***admin***. * **_request** Tell the server which API you want to call. Write down the name of API here. * **key-value pair** If you want to send more information to server, append them into the JSON string in format "key1":"value1", "key2":"value2"…… ### Response When you send a request to API server, it will return you a response. The following is the format of the response: ```json { "code":0, "info":"Success!", "key1":"value1", "key2":"value2", "key3":"value3" } ``` * **code** This is ***error code***. Only you get a success response will the code be 0, otherwise you will get number 1, 2, 3, etc. * **info** It will tell you some valuable infomation of the interaction. **I do hope you can show it to our users.** * **key-value pair** Some extra information the server want to tell you. ## Example This is the most import part of this document. I will show you a complete process to call our APIs. ### Step 1:Obtain base-information First time you open our OMS, you should show some key information, such as our title, our group name, some copyright information, etc. Please obtain them by our API but not show them by pre-written in your software!Because we may update these information anytime. **Send a POST request to** ***https://api.thinker2021.cn***, while the content is: ```json data={ "_username":"null", "_token":"null", "_usertype":"null", "_request":"getBaseInfo" } ``` **Attention**: I write {enter} here purely for aesthetics. You don't need to write '\n' or ' ' when you send the request. you just need to write it in one line without any {enter} or {blankspace}, like: ```json data={"_username":"null","_token":"null","_usertype":"null","_request":"getBaseInfo"} ``` The reason why I set the "_username", "_token" and "_usertype" as "null" is that you haven't got these information right now. So We allow you set them as null only when you call API *getBaseInfo*. Please complete these three parameter when you call any other API. Then the server will give you a response, maybe: ```json { "code":0, "info":"Succuss!", "title":"中小微企业跨组织人才管理系统", "logo":"https://s1.imagehub.cc/images/2021/02/26/logo74cb7888e4dd5a89.png", "cprt":"中小微企业跨组织人才管理系统 Copyright © 2021.02.24-2021.03.20 大连海事大学Thinker™ 思客团队. All rights reserved. ", "firm_name":"Thinker™ 思客" } ``` To learn what they mean, please see the file *API/getBaseInfo*. ### Step 2:Obtain token First time you login OMS, please obtain a token to call other APIs feasible. **Please send a POST request to** ***https://api.thinker2021.cn***, the content is: ```json data={ "_username":"zhangsan", "_token":"e10adc3949ba59abbe56e057f20f883e", "_usertype":"admin", "_request":"login" } ``` The *username* and *token* are entered by the user. But attention, the token here is the password that user inputed and ***encrpted by MD5 algorithm***. Then the server will return you a response like: ```json { "code":0, "info":"Success!", "token":"d6e231066b88fd99c53696d58c6a0992" } ``` Then you can use the token to call other APIs. But attention, the effect time of the token is only 1 hour. Please re-login when the token don't work. ## Developer * Jianhao Sun * Jintao Song * Hongjun An * Ningning Liu *Names are sorted by Alphabet*. Thinker group, Dalian Maritime University, reserves all rights of this project. If you have any question, contact us by ahj@anhongjun.top.