Breve introducción a modelado de API mediante RAML

1. RAML V0.8
MODELADO DE API CON

2. TEXT
CONTRATO

3. AGENDA
▸ Definición
▸ Traits
▸ ResourceTypes
▸ Schemas
▸ Examples
▸ Methods: get, post, delete, put
▸ Tools

4. PARAMETROS GENERALES
#%RAML 0.8
title: Aptitus
baseUri: https://api.aptitus.com/
version: v2
mediaType: application/json

5. GET WITH QUERY PARAMETERS
/institutions:
get:
queryParameters:
q:
description: Text to autocomplete
example: Avancys
responses:
200:
body:
schema: baseInstitutionsGetResponse
example: !include ./examples/base/base.institutions.get.response.json

6. TRAITS - PAGED.RML
queryParameters:
page_size:
description: The number of items per page
type: number
default: 20
page:
description: The page to return
type: number
default: 0
example: 3

7. TRAITS - API.RML
traits:
- paged: !include traits/paged.raml
/institutions:
is: [paged]
displayName: Institutions
get:
description: Get the institutions that match your search.

8. RESOURCETYPES - BASE.RAML
get?:
responses:
200:
description: Returned if the the request invalid.
400?:
description: Returned if the the request is invalid.
404?:
description: Returned if the object is not found.
500?:
description: Returned if an error occurs while retrieving.

9. RESOURCETYPES - API.RAML
/institutions:
type: base
displayName: Institutions
get:
description: |
Get the institutions that match your search.
This service doesn't need that user is logged in.

10. SCHEMAS
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": ["code", "message"]
}

11. SCHEMAS
version: v2
mediaType: application/json
schemas:
- error: !include schemas/error.json

12. EXAMPLES
examples/institutions.get.400.json:
{
"code": 400,
"message": "Debe ingresar una institución"
}

13. EXAMPLES
/institutions:
displayName: Institutions
get:
400:
body:
application/json:
schema: error
example: !include ./examples/institutions.get.400.json

14. MÉTODOS GET WITH QUERY PARAMETERS
/institutions:
get:
queryParameters:
q:
description: Text to autocomplete
example: Avancys
responses:
200:
body:
schema: baseInstitutionsGetResponse
example: !include ./examples/base/base.institutions.get.response.json

15. MÉTODOS GET WITH HEADERS
/synchronize:
get:
headers:
Authorization:
example: Bearer 3b4547126957a718f94540b676fbd0ebc282b5ea
responses:
200:
body:
schema: synchronizeGetResponse
example: !include ./examples/synchronize.get.response.json

16. MÉTODO POST
/oauth2:
/authorize:
post:
body:
schema: oauth2AuthorizePostRequest
example: !include ./examples/identity/oauth2_authorize.post.request.json
responses:
201:
body:
application/json:
schema: oauth2AuthorizePostResponse
example: !include ./examples/identity/oauth2_authorize.post.response.json

17. MÉTODO PUT
/experiences:
/{id}:
put:
body:
schema: postulantExperiencePutRequest
example: !include ./examples/experiences/postulant.experience.put.request.json
responses:
200:
body:
schema: postulantExperiencePutResponse
example: !include ./examples/experiences/postulant.experience.put.response.json

18. MÉTODO DELETE
/experiences:
/{id}:
delete:
description: |
Delete an experience from Postulant. For this service is necessary that the
postulant is logged in.
responses:
200:
body:
schema: postulantExperienceDeleteResponse
example: !include ./examples/experiences/postulant.experience.delete.response.json

19. EXTRA
▸ Documentacion http://raml.org/
▸ Fake api: raml-mockup
▸ Api design: Atom + Api-workbench
▸ Example to Schema http://jsonschema.net/#/
▸ Generate html https://github.com/raml2html/raml2html
▸ Testing https://github.com/cybertk/abao
$ abao api.raml --server http://localhost:8080

20. RAML-MOCKUP
▸ raml-mockup api.raml -d schemas -f http://json-
schema.org -p 5000 -w
▸ Browser: http://localhost:5000/salaries
▸ CLI: $ http POST http://localhost:5000/oauth2/authorize

21. RAML2HTML
▸ raml2html api.raml > ./html/index.html
▸ Open index.html on browser
▸ CLI: $ http http://localhost:8001/#institutions_get