This document outlines the API strategy and specifications for TDISs APIs. It covers the purpose of the APIs, design principles, authentication methods, versioning strategy, and guidelines for documentation.

The primary purpose of our APIs is to provide developers with access to our services and data in a standardized and scalable manner. By offering APIs, we aim to facilitate integration with our platform, enable third-party developers to build applications, and foster innovation in our ecosystem.

Our API design follows these principles:

• Consistency: APIs should have consistent naming conventions, data formats, and error handling.
• Simplicity: APIs should be easy to understand and use, with clear documentation and straightforward endpoints.
• Flexibility: APIs should accommodate various use cases and allow customization where necessary.
• Security: APIs should implement appropriate security measures to protect data and prevent unauthorized access.

We employ OAuth 2.0 for authentication and authorization. Developers must obtain API keys and authenticate requests using OAuth tokens. Access to certain endpoints may require specific permissions granted through OAuth scopes.

All APIs reaquire a valid bearer token to be specified on the Authorization request header.

APIs are versioned using semantic versioning (SemVer). We maintain backward compatibility for existing APIs and introduce new features in a non-breaking manner whenever possible. Changes that introduce breaking changes are released as new major versions.

Versioning through URI Path

$$ /api/v1/ms2 $$

• MAJOR version numbers are mentioned in the URL path (v1) & will be incremented if there is any breaking changes.
• MINOR is not incremented when you add new functionality without breaking the existing API (exported ones) or functionality keeping backward compatible, i.e., a non-breaking change;

These are some of the status codes used by the API

Status Code	Description	Meaning
200	OK	The request was successful.
201	Created	The resource was successfully created.
204	No Content	The request was successful, but no content is returned (e.g., for DELETE requests).
400	Bad Request	The request syntax is invalid or the request cannot be fulfilled.
401	Unauthorized	Authentication credentials are missing or incorrect.
403	Forbidden	The server understood the request, but refuses to authorize it.
404	Not Found	The requested resource does not exist.
405	Method Not Allowed	The requested HTTP method is not allowed for the specified resource.
409	Conflict	The request could not be completed due to a conflict with the current state of the resource.
412	Precondition Failed	The conditions specified in the request headers are not met.
429	Too Many Requests	The user has sent too many requests in a given amount of time.
500	Internal Server Error	An unexpected condition was encountered while processing the request.
503	Service Unavailable	The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

Date and Timestamp Format:

• ISO 8601: Dates and timestamps should follow the ISO 8601 standard format to ensure consistency and interoperability across different systems.

Date Format:

• Dates should be represented in the format YYYY-MM-DD, where:
  • YYYY: Four-digit year (e.g., 2022).
  • MM: Two-digit month (01 for January, 02 for February, etc.).
  • DD: Two-digit day of the month (01 to 31).

Timestamp Format:

• Timestamps should include both date and time components and be represented in the format YYYY-MM-DDTHH:MM:SS, where:
  • T: Separates the date and time components.
  • HH: Two-digit hour (00 to 23).
  • MM: Two-digit minute (00 to 59).
  • SS: Two-digit second (00 to 59).

TDIS APIs enforce a rate limit, which varies according to the API and your usage requirements. When this limit is exceeded, the API will respond with HTTP status code 429 - Too Many Requests. Check with TDIS representative to get the specific limits configured for your account.

API documentation follows the OpenAPI Specification (formerly known as Swagger) format. Each endpoint is documented with details about its purpose, parameters, responses, and examples. Documentation should be comprehensive, up-to-date, and easily accessible to developers.

Our API strategy focuses on providing developers with reliable, well-documented APIs that adhere to established standards and best practices. By following these specifications, we aim to foster collaboration, innovation, and growth within our developer community.

Thank you for your interest in accessing our API services. Please fill out the following Registration Details accurately. Once submitted, your registration will be reviewed by our TDIS team. Upon approval, you will receive your credentials via email.

Our Contact Information:

Email : tdis@tamu.edu

Registration Details:

First Name :
Last Name :
Work Email :
Work Phone :
Agency Name :