Other endpoints

Upload OpenAPI Spec & Get Report

POST

https://api.ratemyopenapi.com

/sync-report

Upload an API spec (OpenAPI v3.x only). A report will be generated synchronously and return the simplified report generated for the spec.

Example request: curl --request POST -H 'Authorization: Bearer YOUR_KEY_HERE' -F 'apiFile=@/path/to/my-openapi.json' --url https://api.ratemyopenapi.com/sync-report

Upload OpenAPI Spec & Get Report › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Upload OpenAPI Spec & Get Report › Request Body

apiFile

string · binary · required

The OpenAPI v3.x spec. JSON and YAML are supported.

Upload OpenAPI Spec & Get Report › Responses

Full Open API report

object

POST/sync-report

curl --request POST \
  --url https://api.ratemyopenapi.com/sync-report \
  --header 'Authorization: <string>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'apiFile=<binary>'

Example Request Body

{
  "apiFile": "<binary>"
}

json

Example Responses

{
  "results": {
    "simpleReport": {
      "version": "1.0",
      "title": "Asana",
      "fileExtension": "json",
      "docsScore": 99,
      "completenessScore": 99,
      "score": 95,
      "securityScore": 87,
      "sdkGenerationScore": 93,
      "shortSummary": "Looks like we have a smorgasbord of issues here. We've got 14 invalid schema examples, because who needs accurate examples anyway? Oh, and don't forget the 1 media example that just couldn't get its act together. But hey, at least we've got some unused components to keep them company!",
      "longSummary": "Well, well, well, looks like we've got ourselves a handful of issues in this OpenAPI file. Let's dive right in, shall we?\n\nFirst up, we have the \"oas3-valid-schema-example\" issue, which has occurred a whopping 14 times! Someone's been a bit too creative with their example values, huh? It's time to reign it in and make sure those examples match the schema. Nobody likes a misleading example, after all.\n\nNext on the list is the \"oas3-parameter-description\" problem, popping up 5 times. Descriptions are like little love notes to your API users, so don't leave them hanging! Make sure you provide clear and concise descriptions for all your parameters. Your users will thank you for it.\n\nLast but not least, we have the \"owasp:api4:2019-rate-limit\" issue, rearing its head a whopping 173 times! Looks like someone forgot to set some boundaries. Implementing rate limiting is a crucial step in protecting your API from abuse. So, set those limits and keep those pesky API abusers at bay.\n\nAlright, that's enough for now. Remember, fixing these high severity issues will go a long way in improving your API. Happy fixing!"
    },
    "reportId": "2617047d-46b2-41f2-b787-f0bf3af84e0a",
    "reportUrl": "https://ratemyopenapi.com/rating/2617047d-46b2-41f2-b787-f0bf3af84e0a"
  }
}

json

application/json

Get your report by ID

GET

https://api.ratemyopenapi.com

/reports/{reportId}

Access your report using the ID given by the /rate endpoint. Note, the report may take a few seconds to generate, during which time you might receive a 404.

Get your report by ID › path Parameters

reportId

string · required

The ID of your report (a uuid)

Example: 7cf20e71-f5df-487b-a145-0825b91db7cd

Get your report by ID › Responses

Success

genericObject

Get Simple Report

GET

https://api.ratemyopenapi.com

/reports/{reportId}/simplified

Fetches the simplified report generated by the Upload OpenAPI Spec endpoint. You may have to wait 10-20 seconds after upload for the report to be generated before fetching it.

Get Simple Report › path Parameters

reportId

string · required

The ID of your report (a uuid)

Example: 7cf20e71-f5df-487b-a145-0825b91db7cd

Get Simple Report › Responses

The simplified API report

version

string

Version of the OAS file.

title

string

Title of the OAS file.

fileExtension

string

File extension of the uploaded spec, either json or yaml.

docsScore

number

The documentation score. Can high quality docs be generated from this API Spec?

completenessScore

number

The completeness score. Does the API spec include many useful, but not required properties?

score

number

The overall score. A combination of the other scores.

securityScore

number

The security score. How secure is the API based on OWASP standards?

sdkGenerationScore

number

The SDK Generation score. How easily can SDK's be generated from this API Spec?

shortSummary

string

A short summary of the issues with the API Spec.

longSummary

string

A longer summary of the issues with the API Spec.

GET/reports/{reportId}/simplified

curl --request GET \
  --url https://api.ratemyopenapi.com/reports/:reportId/simplified

Example Responses

{
  "version": "1.0",
  "title": "Asana",
  "fileExtension": "json",
  "docsScore": 99,
  "completenessScore": 99,
  "score": 95,
  "securityScore": 87,
  "sdkGenerationScore": 93,
  "shortSummary": "Looks like we have a smorgasbord of issues here. We've got 14 invalid schema examples, because who needs accurate examples anyway? Oh, and don't forget the 1 media example that just couldn't get its act together. But hey, at least we've got some unused components to keep them company!",
  "longSummary": "Well, well, well, looks like we've got ourselves a handful of issues in this OpenAPI file. Let's dive right in, shall we?\n\nFirst up, we have the \"oas3-valid-schema-example\" issue, which has occurred a whopping 14 times! Someone's been a bit too creative with their example values, huh? It's time to reign it in and make sure those examples match the schema. Nobody likes a misleading example, after all.\n\nNext on the list is the \"oas3-parameter-description\" problem, popping up 5 times. Descriptions are like little love notes to your API users, so don't leave them hanging! Make sure you provide clear and concise descriptions for all your parameters. Your users will thank you for it.\n\nLast but not least, we have the \"owasp:api4:2019-rate-limit\" issue, rearing its head a whopping 173 times! Looks like someone forgot to set some boundaries. Implementing rate limiting is a crucial step in protecting your API from abuse. So, set those limits and keep those pesky API abusers at bay.\n\nAlright, that's enough for now. Remember, fixing these high severity issues will go a long way in improving your API. Happy fixing!"
}

json

application/json

Get the OpenAPI doc for this API

GET

https://api.ratemyopenapi.com

/openapi

Download the OpenAPI doc powering this documentation.

Get the OpenAPI doc for this API › Responses

Success

genericObject

Upload OpenAPI Spec & Get Report

POST

https://api.ratemyopenapi.com

/sync-report

Upload an API spec (OpenAPI v3.x only). A report will be generated synchronously and return the simplified report generated for the spec.

Example request: curl --request POST -H 'Authorization: Bearer YOUR_KEY_HERE' -F 'apiFile=@/path/to/my-openapi.json' --url https://api.ratemyopenapi.com/sync-report

Upload OpenAPI Spec & Get Report › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Upload OpenAPI Spec & Get Report › Request Body

apiFile

string · binary · required

The OpenAPI v3.x spec. JSON and YAML are supported.

Upload OpenAPI Spec & Get Report › Responses

Full Open API report

object

Get your report by ID

GET

https://api.ratemyopenapi.com

/reports/{reportId}

Access your report using the ID given by the /rate endpoint. Note, the report may take a few seconds to generate, during which time you might receive a 404.

Get your report by ID › path Parameters

reportId

string · required

The ID of your report (a uuid)

Example: 7cf20e71-f5df-487b-a145-0825b91db7cd

Get your report by ID › Responses

Success

genericObject

Get Simple Report

GET

https://api.ratemyopenapi.com

/reports/{reportId}/simplified

Fetches the simplified report generated by the Upload OpenAPI Spec endpoint. You may have to wait 10-20 seconds after upload for the report to be generated before fetching it.

Get Simple Report › path Parameters

reportId

string · required

The ID of your report (a uuid)

Example: 7cf20e71-f5df-487b-a145-0825b91db7cd

Get Simple Report › Responses

The simplified API report

version

string

Version of the OAS file.

title

string

Title of the OAS file.

fileExtension

string

File extension of the uploaded spec, either json or yaml.

docsScore

number

The documentation score. Can high quality docs be generated from this API Spec?

completenessScore

number

The completeness score. Does the API spec include many useful, but not required properties?

score

number

The overall score. A combination of the other scores.

securityScore

number

The security score. How secure is the API based on OWASP standards?

sdkGenerationScore

number

The SDK Generation score. How easily can SDK's be generated from this API Spec?

shortSummary

string

A short summary of the issues with the API Spec.

longSummary

string

A longer summary of the issues with the API Spec.