Interface description language for application programming interfaces
View Patent ↗An application programming interface (API) analysis engine can validate and parse an API specification. It can determine if the API specification (or portion thereof) contains major or minor changes from a previous version of the API specification. The analysis engine can create an intermediate representation of the API. Using the intermediate representation, the analysis engine can generate multiple outputs, such as a client-side SDK, library, etc. as well as documentation and server-side programs. The analysis engine can compare the API specification with a previous API specification and determine backwards compatibility for the API specification. The analysis engine can assign a version number to the API specification. The analysis engine can also provide developer feedback regarding changes that have been made.
1. A method comprising:
generating an application programming interface (API) specification defining API endpoints using data types that are supported in a plurality of programing languages, the data types comprising structs and tagged unions defining respective input data types and output data types for the API endpoints, the API specification being generated in a language that supports struct and tagged union data types;
inputting at least a portion of the API specification into an API engine configured to process and convert the at least the portion of the API specification into a target programming language and serialization format, the target programming language being selected from the plurality of programming languages;
processing and converting, by the API engine using one or more processors, the at least the portion of the API specification into the target programming language and serialization format, to yield a representation of the at least the portion of the API specification in the target programming language and serialization format; and
generating, by the API engine using one or more processors, one or more output files based on the representation of the at least the portion of the API specification, the one or more output files defining one or more of the API endpoints and respective input and output data types, the one or more output files comprising code in the target programming language for communicating data via the API endpoints based on the respective input and output data types and the serialization format.
2. The method of claim 1 , further comprising:
receiving a second API specification that is an earlier version of the API specification;
determining one or more differences between the API specification and the second API specification;
determining a respective backwards compatibility of the one or more differences;
determining a version number of the API specification based at least in part on the respective backwards compatibility, the version number including at least one of a major number and a minor number; and
incrementing the major number based on at least one of:
removal of a field of a user-defined data structure from the API specification;
a change of a type of the field in the user-defined data structure from the API specification;
an addition of a new tag in a first union of the API specification without a catch-all tag;
a change of the type of a tag of a second union of the API specification with a non-Void type; and
a change of the type of a route.
3. The method of claim 1 , further comprising:
receiving a second API specification that is an earlier version of the API specification;
determining one or more differences between the API specification and the second API specification;
determining a respective backwards compatibility of the one or more differences;
determining a version number of the API specification based at least in part on the respective backwards compatibility, the version number including at least one of a major number and a minor number; and
incrementing the minor number based on at least one of:
an addition of a new route to the API specification;
a change of a name of a user-defined data structure of the API specification;
an addition of a field of the user-defined data structure of the API specification that is optional or has a default value;
a change of a type of the user-defined data structure of the API specification from a Void type; and
an addition of a tag to a union of the API specification that has a catch-all.
4. The method of claim 1 , wherein generating the one or more output files comprises generating a module for each namespace in the API specification.
5. The method of claim 4 , wherein generating the one or more output files comprises:
generating a first respective client-side output file in a first programming language for each module; and
generating a second respective client-side output file in a second programming language for each module.
6. The method of claim 1 , wherein the API specification defines, for each of the API endpoints, a request type and a response type without relation to each other such that a type of output from an API endpoint is irrespective of an input to that API endpoint.
7. The method of claim 1 , wherein the API specification includes an input validation parameter, the method further comprising:
generating a server-side output file including instructions for implementing the input validation parameter.
8. The method of claim 1 , further comprising:
presenting developer feedback corresponding to one or more differences between the API specification and a second API specification that is an earlier version of the API specification.
9. The method of claim 1 , further comprising:
determining that the API specification complies with API specification formatting guidelines; and
generating the representation of the API specification at least partly in response to determining that the API specification complies with API specification formatting guidelines.
10. A non-transitory computer-readable medium having computer readable instructions that, when executed by one or more processors, cause the one or more processors to:
receive an application programming interface (API) specification defining API endpoints using data types that are supported in a plurality of programing languages, the data types comprising structs and tagged unions defining respective input data types and output data types for the API endpoints, the API specification being generated in a language that supports struct and tagged union data types;
input at least a portion of the API specification into an API engine configured to process and convert the at least the portion of the API specification into a target programming language and serialization format, the target programming language being selected from the plurality of programming languages;
process and convert, via the API engine, the at least the portion of the API specification into the target programming language and serialization format, to yield a representation of the at least the portion of the API specification in the target programming language and serialization format; and
generate, via the API engine, one or more output files based on the representation of the at least the portion of the API specification, the one or more output files defining one or more of the API endpoints and respective input and output data types, the one or more output files comprising code in the target programming language for communicating data via the API endpoints based on the respective input and output data types and the serialization format.
11. The non-transitory computer-readable medium of claim 10 , wherein the instructions, when executed by the one or more processors, further cause the one or more processors to:
receive a second API specification that is an earlier version of the API specification;
determine a respective backwards compatibility of one or more differences between the API specification and the second API specification;
determine a version number of the API specification based at least in part on the respective backwards compatibility, the version number including at least one of a major number and a minor number; and
increment the major number based on at least one of:
removal of a field of a user-defined data structure from the API specification;
a change of a type of a field in a user-defined data structure from the API specification;
an addition of a new tag in a union of the API specification without a catch-all tag;
a change of a type of a tag of a union of the API specification with a non-Void type; and
a change of a type of a route.
12. The non-transitory computer-readable medium of claim 10 , wherein the instructions, when executed by the one or more processors, further cause the one or more processors to:
receive a second API specification that is an earlier version of the API specification;
determine a respective backwards compatibility of one or more differences between the API specification and the second API specification;
determine a version number of the API specification based at least in part on the respective backwards compatibility, the version number including at least one of a major number and a minor number; and
increment the minor number based on at least one of:
an addition of a new route to the API specification;
a change of a name of a user-defined data structure of the API specification;
an addition of a field of a user-defined data structure of the API specification that is optional or has a default value;
a change of a type of a user-defined data structure of the API specification from a Void type; and
an addition of a tag to a union of the API specification that has a catch-all.
13. The non-transitory computer-readable medium of claim 10 , wherein generating the one or more output files comprises generating a module for each namespace in the API specification.
14. The non-transitory computer-readable medium of claim 10 , wherein generating the one or more output files comprises:
generating a first respective client-side output file in a first programming language for each module; and
generating a second respective client-side output file in a second programming language for each module.
15. The non-transitory computer-readable medium of claim 10 , wherein the API specification defines, for each of the API endpoints, a request type and a response type without relation to each other such that a type of output from an API endpoint does not change based on a type of input to that API endpoint.
16. The non-transitory computer-readable medium of claim 10 , wherein the API specification includes an input validation parameter and wherein the instructions, when executed by the one or more processors, further cause the one or more processors to:
generate a server-side output file including instructions for implementing the input validation parameter.
17. The non-transitory computer-readable medium of claim 10 , wherein the one or more output files comprise a software development kit based on the target programming language, the software development kit containing the code and defining the one or more of the API endpoints and respective input and output data types.
18. The non-transitory computer-readable medium of claim 10 , wherein the instructions, when executed by the one or more processors, further cause the one or more processors to:
determine that the API specification complies with API specification formatting guidelines; and
generate the representation of the API specification according to the formatting guidelines.
19. A system comprising:
one or more processors; and
memory including instructions that when executed by the one or more processors, cause the system to:
receive an API specification defining API endpoints using data types that are supported in a plurality of programing languages, the data types comprising structs and tagged unions defining respective input data types and output data types for the API endpoints, the API specification being generated in a language that supports struct and tagged union data types;
input at least a portion of the API specification into an API engine configured to process and convert the at least the portion of the API specification into a target programming language, the target programming language being selected from the plurality of programming languages;
process and convert, by the API engine, the at least the portion of the API specification into the target programming language, to yield a representation of the at least the portion of the API specification in the target programming language; and
generate, by the API engine, one or more output files based on the representation of the at least the portion of the API specification, the one or more output files defining one or more of the API endpoints and respective input and output data types, the one or more output files comprising code in the target programming language for communicating data via the API endpoints based on the respective input and output data types and a particular serialization format.
20. The system of claim 19 , wherein the one or more output files comprise a software development kit based on the target programming language, the software development kit containing the code and defining the one or more of the API endpoints and respective input and output data types.