Technical Writer - API Documentation (5-9 yrs)
HR Works Consultancy
posted 19hr ago
Key skills for the job
Job Description :
The ideal candidate will define and document RESTful APIs for complex systems, ensuring clarity, structure, and adherence to best practices.
This role is perfect for professionals who excel at translating business requirements into detailed API specifications while collaborating with engineering and product teams to enhance API usability and efficiency.
Job Responsibilities :
- Write clear, structured, and detailed API specifications, ensuring comprehensive endpoint documentation.
- Define data schemas, business rules, and validation logic, incorporating cross-resource dependencies.
- Establish error handling standards and validation rules to improve API reliability and consistency.
- Collaborate with engineering and product teams to refine API specifications and ensure seamless integration.
- Develop API documentation using Markdown, OpenAPI/Swagger, JSON Schema, and tools such as Postman or Stoplight.
Job Requirements :
- API Design Expertise - Experience in designing RESTful APIs for complex systems, handling at least 5+ related API resources (e.g., database tables, microservices).
- Data Modeling & Schema Design - Strong understanding of relational and non-relational data structures, constraints, and validation rules.
- API Documentation Standards - Proficiency with Markdown, OpenAPI/Swagger, JSON Schema, and documentation tools like Postman, Stoplight, or ReadMe.io.
- Technical Writing - Ability to write clear, structured, and unambiguous API specifications, covering business rules and edge cases.
- HTTP & REST Protocol Knowledge - Deep understanding of HTTP methods, response codes, headers, authentication, and error handling.
- API Lifecycle Management - Familiarity with API versioning strategies, deprecation policies, and backward compatibility.
- Testing & Validation - Experience with API contract testing, automated validation, and error response consistency.
Domain Knowledge :
- Business Logic Translation - Ability to convert complex business requirements into well-structured API specifications.
- Cross-Resource Rules - Expertise in defining relationships, dependencies, and constraints across multiple API resources.
- Edge Case Handling - Ability to anticipate and document exceptional scenarios and fallback mechanisms.
- Validation Logic- Strong understanding of input validation, error messages, and business rule enforcement.
Soft Skills :
- Exceptional Technical Writing - Ability to produce detailed, precise, and easy-to-understand documentation in professional English.
- Attention to Detail - Ensures that schemas, business rules, and validation logic are meticulously defined.
- Systems Thinking - Understands how API components interact within larger system architectures.
- Problem Solving & Conflict Resolution - Can navigate technical trade-offs, edge cases, and changing requirements effectively.
- Collaboration & Adaptability - Works effectively with engineering, product teams, and stakeholders to refine API specs.
Deliverable Expectations :
- Candidates must demonstrate the ability to create API PRDs that include :
- Complete Data Schemas - All fields, types, constraints, and relationships.
- Comprehensive Endpoint Documentation - Including request/response examples, parameters, and authentication details.
- Business Logic & Validation Rules - Both resource-specific and cross-resource rules.
- Detailed API Endpoints & Error Handling - Covering status codes, failure scenarios, and best practices for API consumers.
- Implementation Guidance - Ensuring development teams can execute API designs without ambiguity.
Total Years Of exp : 5+ years
Mandatory Skills :
- API Documentation : 3 years, Technical Writing - 3 yrs, RestAPI - 3 yrs
- Opportunity : Full-time, contractual, 4 - 5 hours, PST
Functional Areas: Other
Read full job description