API Design

Our company has a database with roughly 1-million users and growing 500+ users daily. Now that we have users on our website, we want to create an open API to allow 3rd parties to develop solutions that our users would like to help them interact safely with the data they've already entered on our website. This could be activity tracking, appointment scheduling, nutrition tracking, general records updating, and more. Specifically we need someone with experience spec'ing, designing, and defining web APIs. That means we need to speak with each other about use cases, what the overall API design approach should be, and defining those APIs for the data they send and what can be sent back. In addition, we need help writing tests against those APIs using a mock server. We are also looking for thoughts on authentication and management of software developers looking to utilize our APIs and how best to control their access in the event of abuse of our APIs where we need to turn-off access. Lastly, we need to create documentation for those APIs and share those out with a community to help support early adopters through documentation, forum questions & answers, and so on. You must be a seasoned developer who has years of experience not only using APIs but can demonstrate and provide examples for APIs you have created either individually or as part of a team. --- API Language: PHP7 Stack: LAMP Output: JSON/Application CMS: Drupal 7 Documentation: Open API Methods: POST and GET -- We require: 1) Use cases - we have an initial list and would like to see if you have more to add 2) API strategy - basic auth vs oAuth? Naming convention? API key management? Documentation? Support? 3) API definitions - endpoints, data to send, data returned 4) Documentation - Open API format for easy consumption by developers - sample code in multiple languages 5) Testing - preferably test-first development as the APIs are initially declared -- We know what tools we think we want to use. Are we on the same page? -- that is, what tools would you use in doing an API design that would support testing, documentation, team collaboration, and roll-out to an ecosystem to support consumers of the API?