Rough checklist to keep in mind when designing an API:

1. Naming functions right for internal clarity: Ensure function names are descriptive and follow a consistent naming convention.

def get_profiles

2. Naming routes right for external clarity: Use meaningful and intuitive route names that clearly indicate their purpose:

get 'users/fetch_profiles', to: 'users#get_profile'

3. Using the correct HTTP Methods:
GET: Retrieve data.

POST: Create new resources.

PUT: Update existing resources.

PATCH: Partially update existing resources.

DELETE: Remove resources.

post 'users/update_profile', to: 'users#update_profile'

4. Choosing the right authentication technique: Consider using OAuth, API keys, JWT, or other suitable authentication methods based on the security requirements.

def verify_signature
    provided_signature = request.headers['X-Signature']
    payload = request.raw_post
    # Compute the HMAC digest based on the payload of the request
    computed_signature = OpenSSL::HMAC.hexdigest('sha256', SECRET_KEY, payload)
    unless ActiveSupport::SecurityUtils.secure_compare(computed_signature, provided_signature)
      render json: { error: 'Invalid signature' }, status: :unauthorized
    end
  end

5. Deciding on Parameters and Their Types: Define the parameters the API will accept and their data types (query parameters, path parameters, body parameters).

def get_profile (int profile_id, char user_name, char location)

6. Designing the Return Object Structure: Standardize the structure of the returned objects for consistency.

{
profile_id: 10,
user_name: 'Rushi Patel'
location: 'Canada'
settings: {mode: 'dark', zoom: 100, language: 'EN'}
}

7. Pagination and Limits: Set limits and implement pagination to handle large data sets efficiently.

query = query.limit(params[:limit] || 5000)

8. Handling Errors: Provide clear and consistent error messages and use appropriate HTTP status codes.

if !params[:limit].present? || params[:limit].to_i > 5000
      render(json: { error: 'Limit must be present and less than 5000' }, status: :bad_request) and return
end

9. Versioning the API: Implement versioning (e.g., v1, v2) to manage changes and updates without disrupting existing clients.

get 'users/fetch_profiles/v2', to: 'users#get_profile_v2'

def get_profiles_v2

end

Written by,
Rushi Patel

[Tech][API] API Design Checklist

Rough checklist to keep in mind when designing an API: