Rest API is something that really interesting and fun to work with. It enables communication between different software systems over the internet, typically using HTTP protocol. However, Rest API can be difficult sometimes due to its complex queries and filtering, and also batch operations and side effects, etc…Good thing is I went through this blog written by “Medium”. They explained some of the good tips for us to practice with REST API calls. I will walk through their ideas and plans to help us be better at REST API.
Here is their blog https://medium.com/epignosis-engineering/rest-api-development-tips-and-best-practices-part-1-9cbd4b924285
- Planning
- Do research first: Study existing REST API designs, standards, and popular APIs. Consider whether REST is the right paradigm, but also explore alternatives like GraphQL.
- Look at other APIs: Try working with well-known APIs (GitHub, Stripe, Twitter, Paypal) to understand what work and what doesn’t
2. Foundations Matter
- A solid early foundation avoids costly refactors later.
- Assume the API will grow: design for scale, future endpoints, versioning, pagination, analytics, etc.
3. Specification
- Write an API spec before coding
- Use tools like OpenAPI/Swagger for designing your API contract
- Specification pays off – especially for APs that are not just internal
4. Testing
- Critical for APIs: because they connect server data with clients, they need to be very reliable
- Don’t rely solely on manual testing – build an automated test suite
- Focus on functional (black-box) tests, not just unit tests
- Use a test database that can be reset; include regression tests for past bugs
5. Deploymemt
- Decouple your API from other server apps: keep the API as a separate module.
- Why? So updating or deploying one part doesn’t risk breaking everything else.
- Independent deployments make development and operation safer and simpler.
6. Other Good Practices
- Be consistent in resource naming: choose either singular or plural for your endpoints (
/carvs/cars), but don’t mix. - For PUT or PATCH requests, return the updated resource in the response so clients know its new state.
- Avoid using multiple forms of authentication or session mechanisms: for example, don’t mix custom tokens with default PHP session cookies (
PHPSESSID) — it leads to confusion. - Don’t leak internal errors (e.g., SQL errors) to API consumers. Log the details internally, but return a generic 500 error externally for security reasons.
Why This Matters
- The article is very practical: instead of rehashing REST theory, it focuses on avoiding pitfalls the author has personally encountered.
- By planning, specifying, versioning properly, and testing early, you build a more stable and maintainable API.
- A thoughtful deprecation strategy and good error-handling also improve reliability and developer experience for your API clients.
From the blog CS@Worcester – Nguyen Technique by Nguyen Vuong and used with permission of the author. All other rights reserved by the author.



