EnviroChain API. Version /18/17

Transcription

1 EnviroChain API Version /18/17

2 Table of Contents 1 API Features Versioning Logging Swagger Data Model Workflows Lab User Creates a CoC User Authentication User Get User by ID Get User by Address Create a new User Client Get Client By ID Get Client By User ID Create a new Client Project Get Project by ID Get Client Projects Create a new Project CoC (Chain of Custody) Get CoCs for current user Get CoC by ID Create a new CoC Sample Get Sample by ID Add a new Sample to CoC Matrix Get all the Matrices Analytic Methods... 24

3 11.1 Get all the Methods for current user Get a Method by Id Get Sample Methods Create a new Method Add Methods to a Sample Laboratory Get Lab by ID Laboratory Branch Get Branch by ID Get Lab Branches Get User Lab Branches Lab (Branch) Contacts... 32

4 1 API Features 1.1 Versioning Generally, there are three options available for API versioning: 1. URL Requesting a specific version of API as part of the URL ex: 2. URL Parameter Adding api-version parameter ex: 3. Custom HTTP header Specifying the API version as a custom HTTP header ex: api-version: 2.0 Options 1 and 2 require to modify the URL when the API version changes which is not very desirable. Therefore, EnviroChain API takes advantages of the third approach, custom HTTP header, which is hidden from the users and can apply without changing the URL. The EnviroChain API always returns the list of supported versions in api-supported-versions response header: Ex. api-supported-versions: 1.0, 1.1, 1.2 Also the requests can have optional x-version header to request specific version of API (default v1.0): Ex. x-versions: Logging The EnviroChain API takes advantages of ASP.Net Core logging system that is controlled by the Logging settings. "Logging": "Enabled": true, "PathFormat": "Logs/log-Date.txt", "LogLevel": "Default": "Information", "System": "Warning", "Microsoft": "Warning",... Enabled: Turns on or off the logging PathFormat: Specifies the path and also filename format for log files

5 LogLevel.Default: Level of general logging LogLevel.System: Level of system related logging LogLevel.Microsoft: Level of Microsoft components logging Log Levels 1. Information: Includes the Information Level logs and higher levels This includes general messages that helps to track operations and requests to API 2. Warning: Includes the Warning Level logs and higher levels This does not include Information messages 3. Error: Includes the Error Level logs and higher levels This level only logs errors and failure messages 4. Critical: Includes only the Critical Level logs Note: To see the queries issued to database in the log, set the Microsoft log level to Information 1.3 Swagger Swagger is a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation ( The EnviroChain API is instrumented with Swagger which provides API definition in JSON and also an interactive UI to explore the API endpoints. The API s Swagger JSON definition can be accessed from and the interactive API explorer is available at

6 2 Data Model The diagram below shows the data entities that are covered by this API Company 1-* Branch User 1-* Client 1-* 1-* 1-* *-1 Project 1-* Sample Project Detail 1-* Matrix

7 3 Workflows 3.1 Lab User Creates a CoC Lab User Search User by Found User? No Search Client by User ID Found Client? No Search Project by Client ID No Add Samples to CoC

8 4 User Authentication Authenticate user and obtain access token URL: Method: POST Content-Type: application/json Request Body: " ": "password": "mypassword" "token": "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9.eyjzdwiioijqaw1adgvycmf ", "expiration": " T06:53:06Z" Notes: The returned token should be included in subsequent API calls in form of: Authorization: bearer <access-token> expiration shows the time that token expires. The duration of the token can be set in API configuration, under token->duration It s recommended to use SSL for this call since it transfers the user s credentials to the server

9 5 User 5.1 Get User by ID Returns User details by passing ID URL: Request Body: None "id": 13326, " ": "firstname": "David", "lastname": "Smith", "title": "", "phone": " ", "mobile": " ", "company": "XYZ Inc." 5.2 Get User by Address Returns User details by passing its Address URL:

10 Request Body: None "id": 13326, " ": "firstname": "David", "lastname": "Smith", "title": "", "phone": " ", "mobile": " ", "company": "XYZ Inc." 5.3 Create a new User Adding a new User by minimal details (used by lab users) Allowed by Admin or Lab Users only URL: Method: POST Content-Type: application/json Request Body: " ": "johns@acme.com", "firstname": "John", "lastname": "Smith", "title": "Inspector", "phone": " ", "mobile": " " Response Header: Location: <URL to retrieve newly inserted User>

11 Response Body: "id": 13321, " ": "firstname": "John", "lastname": "Smith", "title": "Inspector", "phone": " ", "mobile": " ", "company": null

12 6 Client 6.1 Get Client By ID Returns client details by ID URL: Request Body: None "id": 90, "name": "ABC Co", "userid": Get Client By User ID Returns list of clients for specific user URL: Request Body: None [ "id": 90,

13 "name": "ABC Co", "userid": 6, ] 6.3 Create a new Client Adding a new Client by minimal details (used by lab users) Allowed by Admin or Lab Users only URL: Method: POST Content-Type: application/json Request Body: "name": "ABC Corp", "userid": Response Header: Location: <URL to retrieve newly inserted Client> Response Body: "id": 7833, "name": "ABC Corp", "userid": 13378

14 7 Project 7.1 Get Project by ID Returns a project by ID URL: Request Body: None "id": 850, "name": "XYZ Project", "clientid": 90, "client": "123ENR", "userid": 6, "user": "Joe Smith", "fielddatarequired": true, "fielddatatype": "Standard" 7.2 Get Client Projects Returns list of projects for specific client URL:

15 Request Body: None [ "id": 85, "name": "XYZ Project", "clientid": 90, "client": "ABC Co", "userid": 6, "user": "Jim Smith", "fielddatarequired": true, "fielddatatype": "Standard", ] 7.3 Create a new Project Adding a new Project URL: Method: POST Content-Type: application/json Request Body: "name": "proj 3", "clientid": 90, "userid": 6, "fielddatarequired": true, "fielddatatype": "Standard"

16 Response Header: Location: <URL to retrieve newly inserted Project> Response Body: "id": 10248, "name": "proj 3", "clientid": 90, "client": "NCDENR", "userid": 6, "user": "Jim Smith", "fielddatarequired": true, "fielddatatype": "Standard" Notes: Project Type is set to Other by default For fielddatatype the API only accepts Standard and ADaPT values If there is already a project with same name for same user and same client, API returns an error

17 8 CoC (Chain of Custody) 8.1 Get CoCs for current user Returns a list of CoCs belong to current user URL: Request Body: None [ ], "id": 242, "userid": 6, "clientid": 90, "projectid": 85, "labid": 2663, "labcontactid": 475, "labworkorderid": null 8.2 Get CoC by ID Returns a CoC by ID URL:

18 Request Body: None "id": 30336, "labworkorderid": "abx1234", "client": "id": 7833, "name": "ABC Corp", "userid": 13378, "user": "id": 13378, " ": "firstname": "Ron", "lastname": "Farko", "title": "CEO", "phone": " ", "mobile": " ", "company": null, "project": "id": 85, "type": "Long-Term Monitoring/MNA", "name": "XYZ Project", "labcontact": "id": 475, "labid": 2663, "name": "James Young", "phone": " ", " ": "isactive": 1,

19 "branch": "id": 1791, "userid": 6, "address1": "5041 Taravella Road", "address2": "", "city": "Marrero", "state": "LA", "zipcode": "70072", "country": "USA", "phone": "(504) ", "fax": null, "ishq": true, "samples": [ "id": 2743, "cocid": 1241, "name": "Test", "matrixid": 6, "matrixname": null, "sampledate": " T00:00:00", "sampletime": "07:39", "id": 2744, "cocid": 1241, "name": "Test", "matrixid": 6, "matrixname": null, "sampledate": " T00:00:00", "sampletime": "07:40" ]

20 8.3 Create a new CoC Creates a new CoC URL: Method: POST Content-Type: application/json Request Body: "userid": 13378, "clientid": 7833, "projectid": 85, "labid": 1791, "labcontactid": 123, "labworkorderid": "abx1234" Response Header: Location: <URL to retrieve newly inserted CoC> Response Body: "id": 30338, "userid": 13378, "clientid": 7833, "projectid": 85, "labid": 1791, "labcontactid": 123, "labworkorderid": "abx1234" Notes: Users and Lab Admins only can use the lab ID of the lab branches they have access to

21 9 Sample 9.1 Get Sample by ID Returns a Sample by ID URL: Request Body: None "id": 27972, "cocid": 26254, "name": "11111", "matrixid": 5, "matrixname": "Soil", "guid": "27972", "sampledate": " T00:00:00", "sampletime": "08:35", "tat": 15, "containercount": 1, "type": "", "depthto": "21", "depthfrom": "12", "depthunit": "m", "latitude": " ", "longitude": " ", "timezone": "4", "comment": " look at right date ", "methods": [

22 "id": 3443, "analyticmethod": "527", "name": "Pesticides and Flame Retardants ", "guid": null, ] 9.2 Add a new Sample to CoC Creates a new Sample under specific CoC URL: Method: POST Content-Type: application/json Request Body: "name": "Test4", "matrixid": 8, "sampledate": " ", "sampletime": "", "TAT": 5, "containercount": 3, "type": "Grab", "guid": "12345", "comment": "this is a new sample" Response Header: Location: <URL to retrieve newly inserted Sample> Response Body:

23 "id": 31788, "cocid": 242, "name": "Test4", "matrixid": 8, "matrixname": null, "guid": "12345", "sampledate": " T00:00:00", "sampletime": "", "tat": 5, "containercount": 3, "type": "Grab", "depthto": null, "depthfrom": null, "depthunit": null, "latitude": null, "longitude": null, "timezone": null, "comment": "this is a new sample"

24 10 Matrix 10.1 Get all the Matrices Returns list of all Matrices URL: Request Body: None [ "id": 13, "name": "", "description": "", "id": 4, "name": "Air", "description": "Air", "id": 93, "name": "Aqueous", "description": "Aqueous", ]

25 11 Analytic Methods 11.1 Get all the Methods for current user URL: Request Body: None [ "id": 4175, "analyticmethod": "Volatile Organics", "name": "625", "userid": 6, "categoryid": 14, "categoryname": null, "matrixid": 8, "labid": 0, "country": "USA", "organization": "", "description": "Volatile Organics", "notes": null, "isprepmethod": false, "guid": null, ]

26 11.2 Get a Method by Id URL: Request Body: None "id": 3208, "analyticmethod": "SM 9221A", "name": "Total Coliforms", "userid": 6, "categoryid": 13, "categoryname": "Organics", "matrixid": 5, "labid": null, "country": "USA", "organization": "Standard Methods", "description": "Multiple-tube Fermentation Technique for Members of the Coliform Group", "notes": "", "isprepmethod": null, "guid": null 11.3 Get Sample Methods Returns methods in a sample URL:

27 Request Body: None [ ], "id": 3508, "analyticmethod": "8260B", "name": "VOCs", "userid": 6, "categoryid": 14, "categoryname": "Organics", "matrixid": 8, "labid": 0, "country": "USA", "organization": "EPA", "description": "Volatile Organic Compounds (GC/MS)", "notes": "", "isprepmethod": false, "guid": null 11.4 Create a new Method Creates a new Analysis Method URL: Method: POST Content-Type: application/json

28 Request Body: "analyticmethod": "54321x", "name": "My New method 2", "userid": 9, "categoryid": 14, "matrixid": 8, "labid": 0, "country": "USA", "organization": "EPA", "description": "Test Analysis", "notes": "notes go here", "isprepmethod": true, "guid": "2345" Response Header: Location: <URL to retrieve newly inserted CoC> Response Body: "id": 32911, "analyticmethod": "54321x", "name": "My New method 2", "userid": 9, "categoryid": 14, "categoryname": "Organics", "matrixid": 8, "labid": 0, "country": "USA", "organization": "EPA", "description": "Test Analysis", "notes": "notes go here", "isprepmethod": true, "guid": "2345"

29 11.5 Add Methods to a Sample Adds one or more methods to an existing Sample URL: Method: PUT Content-Type: application/json Request Body: array of method id s [ 201, 245, 305, ] Response Body: None

30 12 Laboratory 12.1 Get Lab by ID Returns a Lab by ID URL: Request Body: None "id": 1150, "name": "XYZ Lab", "website": "

31 13 Laboratory Branch 13.1 Get Branch by ID Returns a branch by ID URL: Request Body: None "id": 1781, "userid": 6, "address1": "10100 Main St", "address2": " Suite 120", "city": "Dallas", "state": "TX", "zipcode": "77000", "country": "USA", "phone": "(713) ", "fax": null, "ishq": true 13.2 Get Lab Branches Returns all the branches belong to specified lab URL:

32 Request Body: None [ "id": 1781, "userid": 6, "address1": "10100 Main St", "address2": " Suite 120", "city": "Dallas", "state": "TX", "zipcode": "77000", "country": "USA", "phone": "(713) ", "fax": null, "ishq": true, ] 13.3 Get User Lab Branches Returns the list of branches that current user has access to, with the option of returning the favorite branches URL: Examples:

33 Request Body: None [ "id": 1781, "userid": 6, "address1": "10100 Main St", "address2": " Suite 120", "city": "Dallas", "state": "TX", "zipcode": "77000", "country": "USA", "phone": "(713) ", "fax": null, "ishq": true, ] 13.4 Lab (Branch) Contacts Returns the list of branch contacts URL: Example: /123/contacts Request Body: None

34 [ "id": 536, "labid": 1781, "name": "test contact", "phone": " ", " ": "isactive": 1,