Fetching Projects (API)
- Julian Montes de Oca (Unlicensed)
The request process typically works in the following manner:
- Authenticate the initiating process/user
- Send project parameter values to DDX
- Response sent to the user with the project's information, including its design data
Methods
Get a project's information
Returns a project's basic information and lists its design phases using the information passed on through the parameters.
Project ID will be required in order to identify the project.
Note: Project ID refers to the id returned by creating a project through the API, instead of the Project Number.
Request
Method | URL |
| GET | api/v1/project_detail |
Method | Request body properties (JSON) | TYPE | Required | Obs |
GET | authToken | String | Yes | |
| GET | projectId | String | Optional (either projectId or id are required) | Refers to the UI's "Project number". |
| GET | id | String | Optional (either projectId or id are required) | It's DDx's ID for the project. |
Sample request:
Note: The authToken was generated in response to /api/v1/authenticate
Response
Status | Response |
200 | Example responses will be shown below- {"projectName": "Some project name", "projectId": "est_ocp_test4", "status": "Active", "projectCategory": "Whole building", "constructionTypeName": "New construction", "officeLocation": "Colonia Office", "country": "UY", "state": "Colonia", "city": "Colonia del Sacramento", "zipcode": "70000", "climateZone": null, "designEnergyCode": "ASHRAE 90.1-2001", "baselineEUI": 99.8, "estimatedOccupancyYear": 2025, "energyTarget": 20.2, "renewables": null, "useType1": "Parking", "useType1Area": 1000, "updatedAt": "2022-01-24T19:37:47.000Z", { "reportingYear": 2020, "projectPhase": "Concept", "energyModelingTool": null, "predictedEUI": 51.896, "lightingPowerDensity": 23.15, "windowToWallRatio": 40, "electricityProducedOffSite": null, "naturalGasCombustedOnSite": null, "districtSteam": null, "diesel": null, "electricityFromRenewablesOnSite": null, "occupancySensorsIncluded": "NO", "daylightingSensorsIncluded": "NO", "chillerType": null } ] } |
400 | {"error": {message: "Invalid Value or Mandatory values are missing."} } Note: List of all error messages provided in appendix below |
401 | {"message": "Invalid Auth Token."} |
401 | {"message": "Auth Token Expired."} |
| 404 | {"message": "Project not found."} |
500 | {"error":"Something went wrong. Please try again later."} |
API Testing & Calls
Sample API Request For User Authentication-
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"user_key":"8TNCKY7VCDA7B4FRP","firm_key":"ABCDEF12346"}'
Test API URL For Authentication-
https://stg-2030ddx.aia.org/api/v1/authenticate
Test API URL For GET Project
https://stg-2030ddx.aia.org/api/v1/project_detail
Production API URL for Authentication
https://2030ddx.aia.org/api/v1/authenticate
Production API URL for GET Project
https://2030ddx.aia.org/api/v1/project_detail
Fetching all firms' projects
Returns all projects' basic information and lists its design phases using the information passed on through the parameters.
Request
Method | URL |
| GET | api/v1/projects |
Method | Request body properties (JSON) | TYPE | Required | Obs |
GET | authToken | String | Yes |
Note: The authToken was generated in response to /api/v1/authenticate
Response
Status | Response |
200 | Example responses will be shown below- [{ "updatedAt": "2022-01-24T19:37:47.000Z", |
400 | {"error": {message: "Invalid Value or Mandatory values are missing."} } Note: List of all error messages provided in appendix below |
401 | {"message": "Invalid Auth Token."} |
401 | {"message": "Auth Token Expired."} |
| 404 | {"message": "Project not found."} |
500 | {"error":"Something went wrong. Please try again later."} |
API Testing & Calls
Sample API Request For User Authentication-
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"user_key":"8TNCKY7VCDA7B4FRP","firm_key":"ABCDEF12346"}'
Test API URL For Authentication-
https://stg-2030ddx.aia.org/api/v1/authenticate
Test API URL to Fetch all projects
https://stg-2030ddx.aia.org/api/v1/projects
Production API URL for Authentication
https://2030ddx.aia.org/api/v1/authenticate
Production API URL for GET Project
https://2030ddx.aia.org/api/v1/projects
Status Codes
All status codes are standard HTTP status codes. The below ones are used in this API.
2XX - Success of some kind
4XX - Error occurred on client’s part
5XX - Error occurred in server’s part
Specific field-level errors will be reported.
Status Code | Description |
200 | OK |
201 | Created |
202 | Accepted (Request accepted, and queued for execution) |
400 | Bad request |
401 | Authentication failure |
403 | Forbidden |
404 | Resource not found |
405 | Method Not Allowed |
409 | Conflict Specific field-level errors will be reported |
412 | Precondition Failed |
413 | Request Entity Too Large By default this is 1 MB but it is configurable on the server |
500 | Internal Server Error |
501 | Not Implemented |
503 | Service Unavailable |