The programmers utilize APIs provided by frameworks and libraries to avoid reinventing the wheel and API specifications aid them to fully understand and adequately use these APIs. This paper introduces "contract-based typestate specifications", a new kind ofspecification for documenting programs. Prior work has focused on two kinds of specifications, namely behavioral and temporal specifications. These specifications either target the constraints of API method invocations or, the usage order of API methods to ensure normal behavior. Consequentially, these two types of specifications are treated independently. Another challenge for these state-of-art specifications lies in the form of limited expressiveness to the designers’ intention, as these are unable to demonstrate all the valid choices under same or different constraints. Contract-based typestate specifications capture the essence of behavioral and temporal specifications, yet provide better understanding and ensure valid API usage as required by context, thus providing flexibility of usage.