Functionnal example for API (GET / POST )

[#1]

Bonjour,

I'm looking to have a good example of the informations that I should entered in functionnal document for an API (GET / POST) and also I should include in this api the validation, so any suggestions to manages error during the validations will be appreciate.

Note, this document will be used by the developper so do not specify how they to write the API but I have to give all the information required for the purpose to create the API.

Merci,

Yvon

[sarthak]

Hi @Yvon Cadieux I am not sure I fully understand your question. But I would still give it a shot.

You can use something like http://apistudio.io/ to design/specify your API and then hand it over to your developers to build those APIs.

apistudio is a tool to help you do design first approach for your APIs. It will generate API spec in swagger Json or YAML which you can then import in Apigee's dev portal to create documentation which may look like this : https://developer.payeezy.com/creditcardpayment/apis/post/transactions

Does that help ?

[anilsr]

Dear @Yvon Cadieux ,

Bonjour , Welcome to Apigee Community 🙂

If you are looking to document your APIs (GET/POST) , swagger 2.0 specification & Swagger UI is the best place to get started. Take a look at petstore example documentation here , implemented using open source swagger.

If you are looking to build APIs, A model first approach is a great way to get started. Check open source API builder swagger node. It helps you document your APIs using swagger yaml & build your APIs using Node.JS . Swagger node validates your API definition with actual implementation. It does validation you are looking for & great help for developer who will be implementing APIs.

All above solutions are completely open source & great way to build APIs or expose API documentation.

Cheers,

Anil Sagar

[#4]

Thanks for your sugestion, I'm looking more for a word or any document as analyst that is realy describe the information required to do the API. Should I give only the fields, length, attribute ?? Should I give all the information for the GET, POST, PUT and DELETE

Example create Customer :

What is the best information should I specify in my specification to minimize the gray zone beetween the analyst and the developer ??

GET /Customer:21345 is enough ??

I take any suggestion that will help to create a good document...

Merci,

Yvon

[willwitman]

Hi Yvon,

It sounds like you're looking for general guidance on REST API design. Apigee has an ebook called "Web API Design" -- it talks about how to think about and structure REST APIs. You can also find Apigee Webinars that talk about API Design, but the E-book includes most of the same information you'll hear in the Webinars. There's another Apigee ebook "APIs for dummies" that you can download -- it's more of a high-level overview of APIs from a business perspective.

The API Craft Google group is another place you can find information about API design.

[adas]

@Yvon Cadieux With swagger you do not need to write an elaborate explanation of the fields. The standard template is self explanatory. Using the http://apistudio.io you can get started wuth the petstore example.

It lets you define the verb,query params, request/response spec and specific error codes too. The idea is too keep the spec as self-explanatory as possible and not burden the api developer with too much of documentation. This would also allow you to generate APi docs, that you can then publish on your developer site.