A Qualitative Study of REST API Design and Specification Practices

REST APIs expose web services to clients. Although experts have recommended guidelines for REST API design, there is little empirical evidence regarding the relationship between adherence to guidelines and benefits to API consumers. We interviewed ten REST API designers to understand what practices REST API designers follow, what opinions they have of existing guidelines, and what challenges they face when designing and using APIs. Some guidelines were widely followed, and some were rejected as being inconsistent with good practice. The participants reported additional challenges: authentication and authorization are too hard to implement; specifications and documentation are frequently missing, vague, or outdated; and standard error reporting methods are insufficient for end users and for debugging purposes. Overall, our observations present opportunities for tool developers to significantly improve the situation by assessing and assuring conformance with guidelines; by aligning documentation with specifications and implementations; and by standardizing guidelines for API design.