我正在尝试API Blueprint并发现了一些我不太清楚的事情.
有+ Parameters,但它只是文件的查询参数.如果我现在要描述POST API,我无法记录POST参数(application/x-www-form-urlencoded).JSON也是如此(参见#3).
我试过了
+ Response 403
If the request request is made with HTTP instead of HTTPS.
但这只是将文本添加为身体反应.
如果我返回JSON,我想分别描述每个字段,它的类型和目的.有没有办法做到这一点？
谢谢!
考虑两个资源之间的以下关系
显然,一个学院不是一流的资源.
现在我需要端点来执行以下操作.
POST /faculties/PUT /college/1/facultiesGET /college/1/faculties:相关院系列表.每个都会包含一个自我网址/faculties/1.DELETE /college/1/faculties/1:网址看起来更好,但如何公开这个网址？PUT /college/1/faculties 接受这所大学院系的完整列表.DELETE /sectors/1:看起来不错,但需要照顾缓存/faculties/1/sectors.在这种情况下,什么是更好的方法？我已经阅读了关于公开会员资源的内容,但是通过这种方法,如果一所大学有10个院系,则需要10个单独的http电话才能从会员资格中获取所有这些资源.
而且,这只是完整关系树的一小部分.为了进一步扩展,系统说
此外,在RESTful架构中,客户端永远不应该填充URL.
有什么建议吗？
我的数据结构定义如下:
# Data Structures
## PlayerRank (object)
Represents the minimum amount of data the the client needs to send to give rank information about a particular Player in a particular Played Game.
+ playerId (number, required) - NemeStats unique identifier for the Player.
+ gameRank (number, required) - The corresponding rank of the Player in this Played Game. A rank of 1 means the Player got first place, 2 means second place, and so on.
+ pointsScored (number, optional) - …我正在编辑我正在处理的项目的一些Apiary文档,并且需要表示我的一个API调用的参数是一个日期时间字符串.蜂房似乎在扼杀这个参数的格式,所以我想知道在Apiary中记录这个参数的建议方法是什么.
为了演示,我从Apiary获取了标准的默认文档并修改了Choice文档以获取类似的datetime对象:
## Choice [/questions/{question_id}/choices/{choice_id}/{datetime}]
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
+ choice_id: 1 (required, number) - ID of the Choice in form of an integer
+ datetime: 2015-05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) associated with this choice
最终结果如下:
datetime
05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) that all returned events should be greater than or equal to Example: 2015.
这显然是错误的,甚至写下示例值.破折号(-)是一个特殊的角色,在这里引起悲伤.这样做的推荐方法是什么？
感谢您的时间我有一个POST请求,我想在蓝图养蜂场中记录,标题是这样的:
text/html的
_method:POST
数据[用户] [用户名]:
数据[用户] [口令]:
数据[用户] [记住]:0
我有类似的东西,但我不知道如何完成它:
## login [/users/login/{username}{password}{remember}{ident}]
Login with a user and password
+ Parameters
+ username (required, string, `myname`) ... the username format should follow CakePHP: data[User][username].
+ password (required, string, `whatever`) ... the password format should follow CakePHP: data[User][password]
+ remember (required, number, `0`) ... the remember format should follow CakePHP: data[User][remember]
+ ident (optional, number, `0`) ... the ident format should follow CakePHP: data[User][ident]
### make login [POST]
+ login …我正在编写API的规范,其中响应中包含的字段各不相同.我希望能够提供多个示例来展示这一点.我的用例是:
include参数,允许用户指定要包含在响应中的一些其他字段我希望能做的是这样的:
+ Response 200 (application/json)
{
"id": 1,
"name": "Joe Bloggs",
"email": "joe@example.com"
}
+ Response 200 (application/json)
If `include=telephone` was specified:
{
"id": 1,
"name": "Joe Bloggs",
"email": "joe@example.com",
"telephone": "0123456789"
}
+ Response 200 (application/json)
If the API key has access to address data:
{
"id": 1,
"name": "Joe Bloggs",
"email": "joe@example.com",
"address": [{
"address1": "101 My street",
"address2": "My area"
}]
}
据我所知,尽管您可以提供多个响应,但只有在响应代码或内容类型不同时才能这样做.有没有办法做到这一点？
在API蓝图中,我希望为POST消息指定一个可选的json元素.例子;
### Add a new User [POST]
To add a User send a JSON .....
+ Request (application/json)
{
"name": "A name",
"age": 30
}
如何向API的读者表明API调用中的年龄是可选的,但仍然显示它是一个整数？
〜科林
我正在尝试以云原生方式开发应用程序.我正在尝试API应用程序的第一个设计.
我应该使用哪种API文档工具？哪一个更适合API第一合同？而哪一个适合哪里？
我正在研究API Blueprint中新数据结构语法的可能性,尤其是MSON.是否可以附加或更确切地指定类似图案(正则表达式)的东西？没有找到关于这个主题的任何内容.
如何在API Blueprint定义中使用通用命名类型？
我试着这样:
FORMAT: 1A HOST: http://test.com/
# API Blueprint testing.
## Resource [/resources]
### Action [GET]
+ Response 200 (application/json)
+ Attributes
+ decorated_person (Address Decorator(Person))
# Data Structures
## Person (object)
+ first_name
+ last_name
## Address Decorator (*T*)
+ address
但是Apiary Editor给我的错误:
基本类型'Address Decorator(Person)'未在文档中定义