Skip to main content

REST API Best Practices

Choices

API Questions​

API design questions​

  • What type of API is best suited for the use case? (e.g. REST, GraphQL)

    • REST is more familiar to most developers so for simple use cases may be easier for development. However, if many fetches are necessary with the REST API, GraphQL may reduce fetch handling complexity.
    • GraphQL allows you to request exactly the data you need, in the format you need it, reducing over- or under-fetching of data. REST, on the other hand, defines a fixed set of endpoints, which can lead to over-fetching or multiple round trips to the server.
    • GraphQL enables you to reduce the number of round trips to the server, improving performance in applications with complex data requirements. REST can also be fast, but may require multiple round trips
    • GraphQL can simplify the development and maintenance process by reducing the need for versioning and allowing for backwards compatibility. REST, on the other hand, can require more complex versioning to handle changes to the data model.
    • GraphQL has a growing ecosystem of tools and libraries, including client libraries, IDEs, and testing frameworks, which can simplify development and testing. REST has a well-established ecosystem, but may not have the same level of specialized tooling.
    • GraphQL may be better for Security as it provides more control over the data returned from the server, reducing the risk of over-exposure of sensitive information.
    • GraphQL provides support for real-time updates through subscriptions, while REST typically requires a separate mechanism, such as WebSockets, to support real-

  • How many types of request methods are required?

  • How will the API handle authentication and authorization?

  • What are the expected performance requirements for the API?

  • How will the API handle errors and exceptions?

  • What is the expected throughput for the API?

Infrastructure:​

  • Should the API be deployed on a serverless option like API Gateway or AppSync?

  • Should an EC2 instance with an API server be used?

  • What type of database will the API use?

  • Is caching required for the API?

    • For example API Gateway can be used to cache responses from the API server.
    • API Gateway supports the following types of caching:
    • Response caching: This type of caching caches the response of an API method to reduce the number of calls to the backend and improve performance. The cached responses are stored on Amazon CloudFront's edge locations, allowing the cached responses to be served directly to clients without having to go to the backend.
    • Request caching: This type of caching caches the results of complex computations, database queries, or other heavy operations performed by an API method, reducing the time required to execute the same operation repeatedly. The cached results are stored in a cache cluster, such as Amazon ElastiCache.
    • Custom caching: This type of caching allows you to implement custom caching logic for an API method, providing you with complete control over the caching behavior.

  • How will the API handle scaling?

  • What kind of traffic and load should be expected?

  • What are the expected response times?

  • What are the potential bottlenecks in the system?

Security:​

  • How will the API handle encryption?
  • What are the expected compliance requirements?
  • How will the API handle DDoS?
  • What are the penetration testing requirements?
  • How will the API handle logging and monitoring?
  • What authentication and authorization protocols will be used?
  • What kind of encryption and data protection strategies need to be in place?
  • Are there any infrastructure-level security risks to consider?

Development and maintenance:​

  • How will the API handle versioning?
  • How will the API be tested?
  • How will the API be deployed?
  • How will the API be documented?
  • What are the expected SLA and availability requirements?

Data modeling:​

  • What are the data entities and relationships that the API will be working with?
  • How will the data be stored and accessed?
  • What are the data validation and integrity requirements?
  • How will the data be indexed for performance?
  • How will the data be backed up and restored?

Integration:​

  • How will the API integrate with other systems and services?
  • What are the expected message formats and protocols for integration?
  • How will data be translated and mapped between systems?
  • How will the API handle real-time integration?
  • How will the API handle batch integration?

Monitoring and analytics:​

  • How will the API be monitored for performance and errors?
  • What are the expected logging requirements?
  • How will the API handle tracing and debugging?
  • How will the API handle capacity planning and forecasting?
  • How will the API handle analytics and reporting?
  • What metrics should be monitored to ensure the API is functioning properly?
  • What kind of alerting should be set up to notify of system performance issues?
  • What kind of logging should be in place to track API usage?

Deployment and testing:​

  • How will the API be deployed and configured?
  • What environments are needed?
  • What are the expected testing requirements and methodologies?
  • How will the API handle rollbacks and disaster recovery?
  • How will the API handle scaling and high availability?
  • How will the API handle security and penetration testing?

Governance:​

  • How will the API be governed and managed?
  • What are the expected policies and standards for the API?
  • How will the API handle compliance and regulatory requirements?
  • How will the API handle intellectual property and data rights?
  • How will the API handle third-party integration and partnerships?

Error Handling:​

  • What kind of error codes should be used?
  • What kind of error messages should be displayed?
  • How should errors be tracked and monitored?

Documentation:​

  • What type of documentation should be provided for API usage?
  • What format should be used for API documentation (Markdown, PDF, etc.)?
  • How should the API documentation be kept up to date?

Maintenance:​

  • How often should the API be updated?
  • What kind of maintenance window should be planned?
  • How should any downtime be communicated to users?

Cost:​

  • What is the budget for the API?
  • What kind of resources are available?
  • What kind of infrastructure is already in place?

Compatibility:​

  • What platforms or devices will the API be used on?
  • What kind of databases and web services will the API interact with?
  • What kind of performance requirements are associated with the API?

AWS API Choices​