Scoring API

Let’s talk about the available API endpoints, even though they are all documented in the API itself! 🤠

Available endpoints

1. Verify a file
2. Validate a ZIP file

Verify a file

This POST operation verifies the retrieved file’s content as long as it complies with the OpenAPI specification.

You can verify a file in two ways:

• You can indicate the specification file and type in a JSON with the URL and apiProtocol property.

  E.g.:

  curl --location 'http://localhost:8080/apifirst/v1/apis/verify' \ 
  --header 'Content-Type: application/json' \ 
  --data '{ 
    "url": "https://raw.githubusercontent.com/InditexTech/api-scoring-engine/main/packages/api-cli/samples/myApis/rest/contract/openapi-rest.yml", 
    "apiProtocol": "REST" 
  }' 
  

• You can attach the specification file along with the API specification type in the apiProtocol property.

  E.g.:

  curl --location 'http://localhost:8080/apifirst/v1/apis/verify' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@"/myApis/rest/contract/openapi-rest.yml"' \
  --form 'apiProtocol="REST"'
  

Input type	Parameters	Description	Required
Application/JSON	url	URL to the API Specification file in the repository. For example: https://raw.githubusercontent.com/InditexTech/api-scoring-engine/main/packages/api-cli/samples/myApis/rest/contract/openapi-rest.yml	yes
	apiProtocol	Protocol type that you want to validate. Possible values: "REST", "EVENT" or "GRPC".	yes
Multipart/form-data	File	Binary API specification file.	yes
	apiProtocol	Protocol type that you want to validate. Possible values: "REST", "EVENT" or "GRPC".	yes

Validate a ZIP file

You can certify an API by retrieving a ZIP file of a compressed folder. The folder needs the following repository structure to use the validations request with a ZIP:

├── metadata.yml
└── myApis
    └── samples
        ├── asyncapi-streams
        │   ├── asyncapi.yml
        │   ├── cart_lines_operations.avsc
        │   └── lines_operations_event.avsc
        └── rest
            └── openapi-rest.yml

Being the metadata.yml a file that contains all APIs defined in the repo:

apis:
 - name: # The API name
   api-spec-type:   # API type: grpc, event, rest
   definition-path: # Path to API folder
   definition-file: # API definition file

For example:

apis:
  - name: "REST Sample"
    api-spec-type: rest
    definition-path: myApis/samples/rest
    definition-file: openapi-rest.yml
  - name: "AsyncAPI Streams Sample"
    api-spec-type: event
    definition-path: myApis/samples/asyncapi-streams
    definition-file: asyncapi.yml

This POST operation creates a validation result from a ZIP file (which should contain a repository) or from a repository URL.

You can verify a ZIP file in two ways:

• In the JSON input type, you can retrieve the ZIP file with the required structure setting the URL to it and indicating the parameters you want to validate (Design, Security, Documentation, or all of them) in the validationType property.

  E.g.:

  curl --location 'http://localhost:8080/apifirst/v1/apis/validate' \ 
  --header 'Content-Type: multipart/form-data' \ 
  --header 'Accept: application/json' \ 
  --form 'file=@"/samples/apisGrade.zip"' \ 
  --form 'validationType="DESIGN"' 
  

• In the form-data input type, you can retrieve the ZIP file with the required structure along with the parameters you want to validate (Design, Security, Documentation, or all of them) in the validationType property.

  E.g.:

  curl --location 'http://localhost:8080/apifirst/v1/apis/validate' \ 
  --header 'Content-Type: application/json' \ 
  --data '{ 
    "url": "https://github.com/raw/main/myApis.zip", 
    "isVerbose": false, 
    "validationType": "DESIGN"
  }'
  

Input type	Parameters	Description	Required
Application/JSON	url	URL to the API Specification file in the repository. For example: https://raw.githubusercontent.com/InditexTech/api-scoring-engine/main/packages/api-cli/samples/main.zip	yes
	isVerbose	Boolean attribute that activates the debug mode.	no
	validationType	Scoring module that the microservice evaluates. Possible values: "DESIGN", "DOCUMENTATION", "SECURITY", "OVERALL_SCORE". The default value is the "OVERALL_SCORE".	no
Multipart/form-data	File	Compressed folder ZIP file. It must have the required structure.	yes
	isVerbose	Boolean attribute that activates the debug mode.	no
	validationType	Scoring module that the microservice evaluates. Possible values: "DESIGN", "DOCUMENTATION", "SECURITY", "OVERALL_SCORE". The default value is the "OVERALL_SCORE".	no

You can check this API specification in the API Scoring Engine repository.