REST API Guidelines

Best practices for designing and implementing APIs in LibreApps Desktop.

Overview

Consistency is key to a great developer experience. These guidelines ensure that all APIs in LibreApps Desktop ecosystem behave in a predictable and intuitive way.

Resource Naming

• Use Nouns: Use nouns instead of verbs for resource names (e.g., /users instead of /getUsers).
• Pluralize: Use plural nouns for collections (e.g., /accounts, /notifications).
• Kebab-case: Use kebab-case for multi-word resource names (e.g., /user-profiles).

HTTP Methods

Method	Action	Success Code
GET	Retrieve a resource or collection.	200 OK
POST	Create a new resource.	201 Created
PUT	Update an existing resource (full replacement).	200 OK
PATCH	Update an existing resource (partial update).	200 OK
DELETE	Remove a resource.	204 No Content

Status Codes

• 2xx (Success): The request was successful.
• 4xx (Client Error): The request was malformed or unauthorized (e.g., 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found).
• 5xx (Server Error): An error occurred on the server (e.g., 500 Internal Server Error).

Filtering, Sorting, and Pagination

For collection endpoints, use query parameters to handle filtering, sorting, and pagination:

• Filtering: /api/users?role=admin
• Sorting: /api/users?sort=name,asc
• Pagination: /api/users?page=1&size=20

Best Practices

• ✅ Do this: Return a consistent JSON error object for all 4xx and 5xx errors.
• ✅ Do this: Use HATEOAS (Hypermedia as the Engine of Application State) to provide links to related resources if appropriate.
• ❌ Don't do this: Use GET requests to modify data; always use POST, PUT, PATCH, or DELETE.